---
title: "Error codes reference"
description: "Every AudD API error code, grouped by category, with the typed SDK exception family each maps to and whether it is safe to retry."
slug: "/resources/reference/errors"
section: "reference"
keywords: [audd, error codes, error handling, retry, exceptions]
---

# Error codes reference

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.

```json
{
  "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**

- [Retry strategy](/resources/concepts/retry-strategy)
- [Glossary](/resources/reference/glossary)
- [SDK docs](https://docs.audd.io/sdks)
- [API reference](https://docs.audd.io)