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

# Errors

> Error envelope, full list of error codes, retry guidance, and WebSocket error delivery.

## Error format

All errors share the same envelope.

```json theme={null}
{
  "status": "error",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "model is required"
  },
  "request_id": "01JXXXXXXXXXXXXXXXXXXXXXXX"
}
```

`error.details` may carry additional structured context for some errors. Always log the `request_id` — include it when contacting support.

## Error codes

| Code                        | HTTP | Meaning                                                                | What to do                                                |
| --------------------------- | ---- | ---------------------------------------------------------------------- | --------------------------------------------------------- |
| `MISSING_API_KEY`           | 401  | API key missing or malformed                                           | Check the header/query format — do not retry              |
| `INVALID_API_KEY`           | 401  | Key revoked or not found                                               | Use a valid key — do not retry                            |
| `INSUFFICIENT_BALANCE`      | 402  | Account balance is zero                                                | Top up in the [console](https://platform.typelessapi.com) |
| `ACCOUNT_SUSPENDED`         | 403  | Account deactivated                                                    | Contact support                                           |
| `INVALID_REQUEST`           | 400  | Missing or invalid parameters (including a missing or unknown `model`) | Fix the request — do not retry                            |
| `AUDIO_FORMAT_UNSUPPORTED`  | 400  | Format not one of `wav` / `ogg` / `webm`                               | Re-encode the audio                                       |
| `AUDIO_TOO_LONG`            | 413  | Audio exceeds the duration limit                                       | Split the audio                                           |
| `FILE_TOO_LARGE`            | 413  | File exceeds 50 MB                                                     | Compress or split the file                                |
| `RATE_LIMIT_EXCEEDED`       | 429  | Too many requests per minute                                           | Retry with exponential backoff                            |
| `CONCURRENT_LIMIT_EXCEEDED` | 429  | Too many simultaneous WebSocket connections                            | Close idle connections, then retry                        |
| `TRANSCRIPTION_FAILED`      | 500  | Transcription pipeline error                                           | Retry once; report with `request_id` if persistent        |
| `INTERNAL_ERROR`            | 500  | Unexpected server error                                                | Retry once; report with `request_id` if persistent        |
| `SERVICE_UNAVAILABLE`       | 503  | Backend temporarily unavailable                                        | Retry with exponential backoff                            |
| `CLIENT_DISCONNECTED`       | —    | Client disconnected mid-stream (WebSocket only; appears in usage logs) | —                                                         |

## Retry guidance

* **Safe to retry with backoff**: `SERVICE_UNAVAILABLE`, `RATE_LIMIT_EXCEEDED`
* **Retry once**: `TRANSCRIPTION_FAILED`, `INTERNAL_ERROR`
* **Do not retry**: all 4xx — fix the request, top up, or contact support

## WebSocket errors

Over WebSocket, errors are delivered as an `error` message (see [Stream transcription](/reference/transcribe-stream)); after an `error` message the server closes the connection.