Error codes reference

When a request fails, the API returns status: "error" and an error object with an error_code (a numeric code) and an error_message (a human-readable string). Common error codes are listed here by category. The Retryable column indicates whether the call is safe to retry.

Note: a no-match response is not an error. If no matches are found, the returned result is null (standard) or an empty array (enterprise), with status: "success". Reserve error handling for the codes below.

Authentication

The API token is missing, not valid, or has been disabled. If you retry with the same token, you’ll get the same error, so none of these are retryable. Fix the credential first and try again.

Quota

The token is valid, but the quota limit has been reached. Retrying in the same window returns the same error. If you reach this limit, raise your plan or wait for the quota to reset.

Subscription

The token is valid, but the endpoint, method, or feature you requested is not enabled for it. For example, calling the enterprise or streams endpoints with a token that doesn’t have that access results in one of these errors. These errors are not retryable; the feature has to be enabled on the account first.

Invalid request

The request reached the server but could not be processed because of a malformed or rejected parameter. The request may be resubmitted after correcting the parameter.

Missing file or parameter

One of the required inputs has not been received, and the request can’t be retried until you include it. There are two common reasons for 700 on POST requests. Files must be attached using a multipart/form-data body, so a wrong Content-Type causes this error. A request to an http:// URL can also be redirected, and the request body is empty after the redirect; send it to https:// directly.

Invalid audio

If the input arrives but cannot be used as audio, one of these errors is returned. Sending the same bytes again won’t help: the file is the problem, not the call.

Stream

The limits of the streams subscription have been reached, and the request can’t be retried until the plan changes.

Rate limit

A per-stream daily request limit was exceeded. If you hit this limit, back off and try again after the limit window resets, rather than retrying immediately.

Server and internal

The request was well-formed, but something went wrong on the server. Common causes of an internal error (19) are a server that is down for scheduled maintenance or a transient fault. Internal errors are the only server codes worth an automatic retry with backoff. The others indicate that the request was blocked or that the API method is unknown, and cannot be retried.

How the SDKs surface these

Every official SDK reads the error_code from the response and raises a typed exception for it; no SDK returns raw error blobs. The exception names follow each language’s conventions; the categories are the same in every SDK:

Two more exception families have no server error_code, because the failure occurs either before the wire response or after it:

• Connection error: This error can occur either because the request never reached the server or because no response was received. Common causes are DNS and TLS failures, timeouts, and dropped sockets. The error is transient, so you can retry idempotent calls with backoff.
• Serialization error: Raised when a 200 OK body could not be parsed due to an unexpected shape. This error cannot be retried. The problem is in the payload.

Each typed exception contains two properties from the response, an error_code indicating what type of error has been returned, and a human-readable error_message that describes what the error code means. You can use error_code to determine when a specific code needs its own handling. You can also catch an entire category in one catch block.

Notes

• No-match is not an error. result: null (standard) or an empty array (enterprise) means the request succeeded and matched nothing. No error handling is needed for this result.
• Retry only what is transient. The two retryable cases are connection errors and internal server errors (19). Retry them with exponential backoff. The authentication, quota, subscription, invalid-request, missing-file, and invalid-audio categories require a fix to the input or the account. If you retry them, you will get the same errors.
• Do not auto-retry metered uploads on an ambiguous 5xx. Once an upload has completed, the server may already have done metered work, so a retry after an ambiguous 5xx can bill twice. For this reason, the SDKs do not retry the enterprise upload or a custom-catalog upload automatically.
• 611 needs backoff, not an immediate retry. If you make another request before the daily window resets, then you will hit the rate limit and receive a 611 error.
• The codes shown here are the common ones out of roughly 40 server codes. Any code not listed here is handled by the SDKs as a server error.
• Retry strategy
• Glossary
• SDK docs
• API reference