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

# Errors

> How to handle errors

The Timbal API uses conventional HTTP response codes to indicate the success or failure of an API request.
In general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided (*e.g.*, a required parameter was omitted, a charge failed, etc.). Codes in the `5xx` range indicate an error with Timbal servers (these are rare).

## Rate limiting

Some endpoints enforce **per-user** rate limits. When limits apply, successful **`2xx`** responses and **`429 Too Many Requests`** may include:

| Header                | Meaning                                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `RateLimit-Limit`     | Maximum requests allowed in the current window.                                                |
| `RateLimit-Remaining` | Requests left before the window resets.                                                        |
| `RateLimit-Reset`     | Seconds until the window resets.                                                               |
| `Retry-After`         | On **`429`**, seconds to wait before retrying (prefer this over a fixed backoff when present). |

Legacy aliases **`X-RateLimit-Limit`**, **`X-RateLimit-Remaining`**, and **`X-RateLimit-Reset`** mirror the `RateLimit-*` values.

| Code                           | Status            | Description                                                                                         |
| ------------------------------ | ----------------- | --------------------------------------------------------------------------------------------------- |
| 200                            | OK                | Everything worked as expected.                                                                      |
| 400<br />422                   | Bad Requests      | The request was unacceptable, often due to missing a required parameter.                            |
| 401                            | Unauthorized      | No valid API key provided.                                                                          |
| 402                            | Request Failed    | The parameters were valid but the request failed.                                                   |
| 403                            | Forbidden         | The API key doesn’t have permissions to perform the request.                                        |
| 404                            | Not Found         | The requested resource doesn’t exist.                                                               |
| 429                            | Too Many Requests | Per-user rate limit exceeded. Honor **`Retry-After`** when sent; otherwise use exponential backoff. |
| 500<br />502<br />503<br />504 | Server Errors     | Something went wrong on our end.                                                                    |