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

# Error Handling

> Complete guide to handling errors in the Tiro API

## Error Response Format

All Tiro API errors follow a consistent JSON structure:

```json theme={"system"}
{
  "error": {
    "code": 400001,
    "errorType": "bad_request",
    "message": "Human readable error message",
    "detail": "Additional context or null"
  }
}
```

### Fields

| Field       | Type                     | Description                                                                                                                                                   |
| ----------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`      | integer                  | 6-digit error code in `AAABBB` form: first 3 digits match the HTTP status, last 3 digits are a per-status serial. Use this for fine-grained client branching. |
| `errorType` | string                   | Coarse-grained category derived from the HTTP status. Stable over time — safe for client branching. See table below.                                          |
| `message`   | string                   | Human-readable error message. Not stable; do not use for branching.                                                                                           |
| `detail`    | object \| string \| null | Optional additional context (varies per error).                                                                                                               |

## HTTP Status Codes & Error Types

| Status  | `errorType`            | Meaning                                                      |
| ------- | ---------------------- | ------------------------------------------------------------ |
| **400** | `bad_request`          | Invalid request format or parameters                         |
| **401** | `unauthorized`         | Missing or invalid API key                                   |
| **403** | `forbidden`            | API key lacks required permissions                           |
| **404** | `not_found`            | Resource doesn't exist                                       |
| **406** | `not_acceptable`       | Unsupported `Accept` header                                  |
| **409** | `conflict`             | Resource already exists or state conflict                    |
| **413** | `payload_too_large`    | Request body exceeds size limits                             |
| **422** | `unprocessable_entity` | Valid format but invalid data                                |
| **429** | `too_many_requests`    | Rate limit exceeded                                          |
| **5xx** | `internal_error`       | Server-side error (do not parse further; retry with backoff) |