> ## Documentation Index
> Fetch the complete documentation index at: https://aircaps.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> HTTP errors, job errors and retries.

## HTTP errors

Every error uses one shape:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_language",
    "message": "language 'de' is not supported; only English (\"en\", \"en-US\", ...) is available today. Multilingual support is planned.",
    "param": "language_code",
    "request_id": "req_01k6z..."
  }
}
```

| HTTP | type | code |
| - | - | - |
| 400 | `invalid_request_error` | `invalid_request`, `unsupported_language`, `unsupported_model`; AirCaps Speaker ID-v1 (and `speaker_identification` on transcripts): `invalid_audio`, `audio_too_short`, `audio_too_long`, `no_enrolled_speakers`, `speaker_not_enrolled` |
| 401 | `authentication_error` | `unauthorized` |
| 402 | `invalid_request_error` | `insufficient_balance` |
| 403 | `permission_error` | `account_suspended`, `account_disabled`, `session_required`, `usage_limit_reached`, `model_access_denied` |
| 404 | `invalid_request_error` | `not_found`, `file_not_found`, `speaker_not_found`, `enrollment_not_found` |
| 405 | `invalid_request_error` | `method_not_allowed` |
| 409 | `invalid_request_error` | `idempotency_conflict`, `transcript_not_ready`, `diarization_not_ready`, `speaker_limit_reached`, `enrollment_limit_reached` |
| 413 | `invalid_request_error` | `file_too_large` |
| 429 | `rate_limit_error` | `rate_limited`, `queue_full` (honour `Retry-After`) |
| 500 | `api_error` | `internal_error` |
| 503 | `api_error` | `service_unavailable`: a brief capacity or dependency problem (honour `Retry-After`) |
| 502, 504 | `api_error` | `upstream_unavailable`, `upstream_timeout` (`request_id` is `null`) |

Include `request_id` (also in the `x-request-id` header) when you contact support.

* `unsupported_language`: only English is available today; multilingual support is planned.
* `insufficient_balance`: your free hours and credits are used up. Add credits in the console (or turn on auto refill) to keep going.
* `usage_limit_reached`, `model_access_denied`, `queue_full`: account limits. To raise them, [talk to sales](https://aircaps.ai/contact).
* AirCaps Speaker ID-v1 reports problems with a clip in the response itself (it is synchronous): `invalid_audio` (not decodable or no audio), `audio_too_short` (under 0.5 s; enrollments under 1 s), `audio_too_long` (over 2 minutes), `file_too_large` (over 100 MB). These requests are not counted toward your usage.

## Job errors

A transcript that fails has `"status": "error"` and an `error` object. None of these count toward your usage.

| code | Meaning |
| - | - |
| `invalid_audio` | Not decodable, no audio stream, empty, or shorter than 0.1 s |
| `audio_too_long` | Longer than 10 hours |
| `file_too_large` | Larger than 5 GB |
| `download_failed` | `audio_url` could not be fetched (HTTP error, timeout, non-public address) |
| `file_not_found` | The uploaded file is missing or expired |
| `insufficient_balance` | Costs more than your remaining free hours and credits. Add credits and resubmit |
| `usage_limit_reached` | Longer than your remaining usage ([talk to sales](https://aircaps.ai/contact) to raise it) |
| `internal_error` | Failed on our side after automatic retries. Resubmit; a `file_id` stays usable for 24 hours after upload |

Deleting a queued or processing transcript cancels it: the `DELETE` response shows `error.code` `canceled`, no webhook is sent, and the ID then returns `404`.

## Retries

* Retry `429`, `500`, `502`, `503` and `504` with exponential backoff (for example 1 s, 2 s, 4 s … up to 60 s), honouring `Retry-After` when present.
* Send an `Idempotency-Key` header with `POST /v1/transcripts` so a retried request never creates a second job. A retry with the same key and body returns the original transcript (`200`), even after it has finished.
* Live streaming: on close code 1013, a connection that can't be opened, one that drops without a close message, or one that goes quiet (no message for 30 seconds and no `pong` within 10 seconds of a `ping`), open a new session with backoff (for example 1 s, 2 s, 4 s … up to 30 s). See [Live streaming](https://aircaps.ai/docs/guides/streaming.md#retrying).
* Polling: call `GET /v1/transcripts/{id}` every 3–10 seconds, or use a [webhook](https://aircaps.ai/docs/guides/webhooks.md) instead.
* For large files, prefer an [upload URL](https://aircaps.ai/docs/api-reference/upload-url.md): the bytes go straight to storage, so a retry never re-sends them through the API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.