Error codes reference — AudD resources

When a request fails, AudD returns status: "error" and an error object with a numeric error_code and a human-readable error_message. This page lists the codes, groups them by category, and maps each category to the typed exception family the SDKs raise and whether the call is safe to retry.

A failed request is not the same as a no-match result. A successful request that recognized nothing returns status: "success" with result: null (or an empty array on the enterprise endpoint) — never an error. 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 token is missing, wrong, or disabled. None of these are retryable — retrying with the same token produces the same error. Fix the credential.

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 a usage limit has been reached. Not retryable on the same window — raise the plan or wait for the quota to reset.

Code	Meaning	Retryable
`902`	Token quota exceeded.	No

Subscription

The token is valid but the requested endpoint, method, or feature is not enabled for it (for example, calling the enterprise or streams endpoints with a token that lacks that access). Not retryable; enable the feature on the account.

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 a parameter was malformed or rejected. Not retryable without changing the request.

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

A required input was not received. Not retryable until you include it. For 700, the most common cause on POST is a wrong Content-Type (it must be multipart/form-data) or a redirect from an http:// URL that drops the request body — send 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

The input arrived but could not be used as audio. Not retryable with the same bytes — 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 streams subscription’s limits were hit. Not retryable without a plan change.

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

Rate limit

A per-stream daily request limit was exceeded. Retryable only after the limit window resets — back off 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 the server could not complete it. Internal errors (19) cover transient server faults and scheduled maintenance, and are the only category worth an automatic retry with backoff. The others indicate the request was blocked or the method is unknown — not retryable.

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 error_code off the response and raises a typed exception rather than returning a raw error blob. The categories above map to these exception families (names follow each language’s conventions; the shape is consistent across SDKs):

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 do not correspond to a server error_code because they happen before or after the wire response:

Connection error — the request never reached the server or the response never arrived (DNS, TLS, timeout, dropped socket). Transient; retry with backoff for idempotent calls.
Serialization error — a 200 OK arrived but the body could not be parsed into the expected shape. Not retryable; the payload is the problem.

Each typed exception carries the original error_code and error_message so you can branch on the specific code when you need to, while still being able to catch an entire category.

Notes

No-match is not an error. result: null (standard) or an empty array (enterprise) means the request succeeded and matched nothing. Do not route it through error handling.
Retry only what is transient. Connection errors and internal server errors (19) are the retryable cases; use exponential backoff. The authentication, quota, subscription, invalid-request, missing-file, and invalid-audio categories will return the same error on retry — fix the input or the account instead.
Do not auto-retry metered uploads on an ambiguous 5xx. Once an upload has completed, the server may already have done metered work; an automatic retry can double-bill. The SDKs do not retry the enterprise upload or a custom-catalog upload automatically for this reason.
611 needs backoff, not an immediate retry. It is a rate limit, so the retry only succeeds once the daily window resets.
The server reports roughly 40 codes in total; the codes above are the ones an integration encounters in practice. Any code not listed here is handled by the SDKs as a server error.

Related