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

# Errors & status codes

> The Chariot API error envelope, HTTP status codes, and how to handle each.

Every error returns a consistent JSON envelope with the matching HTTP status code.

## Error envelope

```json theme={null}
{
  "statusCode": 404,
  "error": "EntityNotFoundException",
  "message": "Voice with id: 00000000-0000-0000-0000-000000000000 does not exist!"
}
```

| Field        | Description                                                            |
| ------------ | ---------------------------------------------------------------------- |
| `statusCode` | HTTP status code, echoed in the body.                                  |
| `error`      | Machine-readable error class. Branch on this, not on the message text. |
| `message`    | Human-readable explanation.                                            |

<Note>
  Match on `statusCode` and `error`, not on `message`. Message strings may be refined over time.
</Note>

## Status codes

| Status | `error`                        | Meaning                                                                           |
| ------ | ------------------------------ | --------------------------------------------------------------------------------- |
| `400`  | `BadRequestException`          | The request was malformed.                                                        |
| `401`  | `UnauthorizedException`        | Missing, invalid, or expired API key, or a disallowed origin.                     |
| `403`  | `InsufficientCreditsException` | Not enough credits to complete the request.                                       |
| `403`  | `HTTPException`                | The product is not available on your plan.                                        |
| `404`  | `EntityNotFoundException`      | The voice, inference, or resource does not exist.                                 |
| `422`  | `ValidationException`          | A field failed validation or a business rule (e.g. text length, voice not ready). |
| `422`  | `RequestValidationError`       | The request body or query failed schema validation.                               |
| `429`  | `HTTPException`                | Too many concurrent requests for your plan.                                       |
| `500`  | `ProcessException`             | An unexpected server error. Charged credits are refunded.                         |

## Common errors

### Authentication (401)

| Message                                   | Cause                                                |
| ----------------------------------------- | ---------------------------------------------------- |
| `No API key or user credentials provided` | The `chariotai-api-key` header is missing.           |
| `Invalid API Key or user credentials`     | The key is unknown or malformed.                     |
| `API Key expired`                         | The key has passed its expiry.                       |
| `Unauthorized request!`                   | A public key was used from a non-allowlisted origin. |

### Text to speech

| Status | Message                                                                          | Cause                                         |
| ------ | -------------------------------------------------------------------------------- | --------------------------------------------- |
| `404`  | `Voice with id: ... does not exist!`                                             | Unknown `voice_id`.                           |
| `422`  | `Voice ... is not ready for TTS yet!`                                            | The voice is not yet available for synthesis. |
| `422`  | `Input text of length N is more than maximum character count of 500 characters!` | Text over the 500-character limit.            |
| `403`  | `Workspace has N credits; needs M`                                               | Not enough credits.                           |
| `429`  | `Concurrent request limit exceeded (N) for tts.standard on the current plan`     | Over your plan's concurrency limit.           |

## Handling errors

<AccordionGroup>
  <Accordion title="401: re-check your key and header">
    Confirm the `chariotai-api-key` header is present and the key is active. For public keys, confirm the request origin is on the key's allowlist. See [Authentication](/guides/authentication).
  </Accordion>

  <Accordion title="403: top up or upgrade">
    `InsufficientCreditsException` means you're out of credits, check [`GET /v1/credits`](/api-reference/endpoint/user-credits). A plan `HTTPException` means the product isn't on your plan.
  </Accordion>

  <Accordion title="422: fix the input">
    Validate `voice_id` is a real UUID, keep `text` within 1 to 500 characters, and confirm the voice is available before using it.
  </Accordion>

  <Accordion title="429: back off and retry">
    You've hit your plan's concurrency limit. Retry with exponential backoff and jitter, and cap your in-flight requests. See [Rate limits & concurrency](/guides/resources/rate-limits).
  </Accordion>

  <Accordion title="500: safe to retry">
    An unexpected server error. Any credits charged for the failed request are refunded. Retry after a short delay; if it persists, contact support with the `Inference-Id`.
  </Accordion>
</AccordionGroup>