> For the complete documentation index, see [llms.txt](https://api-docs.speechace.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.speechace.com/getting-started/error-handling.md). # Error Handling Speechace uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the `2xx` range indicate API execution success; The `status` field in the API response indicates wether the scoring request itself was successful or if an error occured due the information provided (e.g., a required parameter was omitted); codes in the `5xx` range indicate an error with Speechace's servers (these are rare). {% hint style="info" %} A `2xx` HTTP status does not always mean the audio was scorable. Always check the JSON `status` field — a request can return `200` with `"status": "error"` and a `short_message`. See [Scoring errors & warnings](/interpreting-results/scoring-errors-and-warnings.md) for signals returned *inside* an otherwise successful score. {% endhint %} #### **HTTP Status Code Summary**

Code	Code Meaning	Description
200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid API key provided.
402	Request Failed	The parameters were valid but the request failed.
403	Forbidden	The API key doesn’t have permissions to perform the request.
404	Not Found	The requested resource doesn’t exist.
409	Conflict	The request conflicts with another request.
429	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504	Server Errors	Something went wrong on the Server's end. (These are rare.)

## Error response format Whenever the API returns an error, the response will appear as follows: {% code title="Sample error response" collapsedlinecount="10" %} ```json { "status": "error", "short_message": "error_invalid_parameters", "detail_message": "key" } ``` {% endcode %} The attributes of the response are: * `status`: whether the response is a success or an error. * `short_message`: the type of error returned — one of the codes in the tables below. * `detail_message`: a human-readable message with more detail (often naming the offending parameter). Branch on `short_message`, not on `detail_message` (which is free text). Note that similar-sounding codes are distinct — for example `error_unknown_words` (a lexicon/parse problem with the text) is **not** `error_feature_unavailable` (the feature isn't offered for your plan, region, or dialect). ## Errors Every `short_message` the API returns, grouped by cause. ### Request & parameters | Error | Cause & solution | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `error_missing_parameters` |

Cause: one or more required API parameters were missing.

Solution: check detail\_message for the missing parameter.

| | `error_invalid_parameters` |

Cause: one or more API parameters were invalid.

Solution: check detail\_message for the offending parameter.

| | `error_invalid_request` |

Cause: the request contains a combination of API version and parameters that does not exist.

Solution: check the version in the endpoint path and the parameter combination against the API Reference.

| | `error_key_expired` |

Cause: your API key is not active.

Solution: check your subscription status or contact .

| ### Audio | Error | Cause & solution | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `error_audio_missing` |

Cause: the audio file was not correctly passed or is missing.

Solution: check the audio form-data field in the request body.

| | `error_audio_empty` |

Cause: an audio file was received but contains no audio (zero bytes or no samples). Distinct from error\_audio\_missing (no file at all) and error\_no\_speech (audio present but no voice).

Solution: verify your recording/upload pipeline is capturing and sending audio.

| | `error_convert_audio` |

Cause: the audio is corrupt or not in a valid format (mp3, wav, webm, aac, etc.).

Solution: check that the file is not corrupt and is in an accepted format.

| | `error_audio_too_long` |

Cause: your audio duration exceeds your API license limit.

Solution: limit the recording length, or contact to upgrade.

| | `error_file_too_large` |

Cause: your audio file size exceeds your API license limit.

Solution: record at the required sample rate and no higher to optimize file size.

| ### Speech & content | Error | Cause & solution | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `error_no_speech` | **Cause:** no human voice detected in the audio. **Solution:** ensure the audio contains clear human speech; this often signals a recording-logic failure. | | `error_other_speech` |

Cause: the audio is entirely different from the expected text.

Solution: ensure the speaker is reading the intended text and that the correct text is being passed.

| | `error_word_alignment` |

Cause: the audio did not align with any of the words in the intended text (often background noise or unclear speech).

Solution: check for background noise and ensure the speech is clear.

| | `error_no_word` | **Cause:** the request's text contained no scorable words (e.g. empty, special characters, or whitespace-only text). **Solution:** supply non-empty text with at least one recognizable word. | | `error_unknown_words` |

Cause: one or more words are outside the Speechace lexicon.

Solution: use the Validate Text API at authoring time to catch these, or pass include\_unknown\_words to handle them automatically.

| | `error_unknown_phonemes` |

Cause: the phoneme sequence supplied (score/phone\_list, or arpa\_mark markup) contains phonemes that are not in the target dialect's phoneme set.

Solution: use only phonemes from the dialect's ARPABET — see Phonetic notation.

| | `error_text_too_long` |

Cause: the submitted text is longer than 1500 characters.

Solution: shorten the text to meet the limit.

| | `error_answer_too_long` |

Cause: a Score Writing submission (answer) exceeds the maximum length for its task\_type.

Solution: keep the answer within the task\_type's word range.

| ### Dialect & features | Error | Cause & solution | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `error_feature_unavailable` |

Cause: you attempted to use a feature not provided in your subscription.

Solution: contact to upgrade your plan.

| | `error_not_supported` |

Cause: the request contains a feature parameter for a feature not supported in the current API region or dialect.

Solution: check the Supported languages coverage matrix and your key's region; use a region/dialect that supports the feature.

| | `non_dialect_language_detected` |

Cause: with language detection (detect\_dialect / enforce\_dialect), the language detected in the audio is not one of Speechace's supported dialects. With enforce\_dialect=1 this is returned as an error.

Solution: have the speaker respond in a supported dialect, or omit enforce\_dialect to score anyway. See Score Speech.

| ### Limits & quota | Error | Cause & solution | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `error_too_many_requests` | **Cause:** you exceeded the allowed concurrent request volume and are being throttled. **Solution:** back off and retry with exponential backoff (see [Retries](#retries)). | ### Server | Error | Cause & solution | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `error_timeout` |

Cause: the request took too long to process and timed out on the server.

Solution: retry; if it persists, reduce the audio length or contact support.

| | `error_internal` |

Cause: a catch-all for unforeseen server-side errors.

Solution: contact for assistance.

| ## Retries On `429 Too Many Requests` (`error_too_many_requests`), back off and retry with exponential backoff. `error_timeout` and the `5xx` / `error_internal` server errors may also be retried. Handle `status: "error"` responses gracefully by reading `short_message` and `detail_message`. If you can't resolve an error, [raise a support ticket](/resources/requesting-support.md).