Error codes reference — AudD resources

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.

{
  "status": "error",
  "error": {
    "error_code": 901,
    "error_message": "No api_token passed, and the limit was reached. Please obtain an api_token."
  }
}

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.

Code	Meaning	Retryable
`900`	Invalid API token. Check the `api_token` parameter.	No
`901`	No `api_token` was passed and the free limit was reached. Obtain a token.	No
`903`	The token has been disabled.	No

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.

Code	Meaning	Retryable
`902`	Token quota exceeded.	No

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.

Code	Meaning	Retryable
`904`	The endpoint or feature is not available with this token, or the referenced user/radio does not exist.	No
`905`	The method is not allowed for this token.	No

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.

Code	Meaning	Retryable
`600`	Incorrect audio URL, a local file path where an upload was expected, or a file sent in the wrong form.	No
`601`	Incorrect stream URL (streams endpoints).	No
`602`	Incorrect callback URL (streams endpoints).	No

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.

Code	Meaning	Retryable
`700`	No file or URL was sent for recognition (or the server did not receive it).	No
`701`	No stream URL was sent (streams endpoints).	No
`702`	No callback URL was sent (streams endpoints).	No

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.

Code	Meaning	Retryable
`300`	Fingerprinting error. Network inference failed; most often the audio clip is too small.	No
`400`	Audio file too large for the standard endpoint (10 MB cap). Use the enterprise endpoint for longer audio.	No
`500`	Invalid audio file. The data could not be decoded as audio.	No

Stream

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

Code	Meaning	Retryable
`610`	Streams limit reached for the subscription.	No

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.

Code	Meaning	Retryable
`611`	Per-stream daily rate limit exceeded.	After reset

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.

Code	Meaning	Retryable
`19`	Internal error, scheduled maintenance, or a request blocked for security/policy reasons.	If transient (backoff)
`100`	Unknown error.	No
`1000`	Unknown API method called.	No

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:

Category	Codes	Exception family
Authentication	`900`, `901`, `903`	authentication error
Quota	`902`	quota error
Subscription	`904`, `905`	subscription error
Invalid request	`600`, `601`, `602`	invalid-request error
Missing file / parameter	`700`, `701`, `702`	invalid-request error
Invalid audio	`300`, `400`, `500`	invalid-audio error
Stream / rate limit	`610`, `611`	quota error (rate-limited)
Server / internal	`19`, `100`, `1000`	server error

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.

Related