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

# Error handling

> Hub for API errors, SLA/escalation behavior, and troubleshooting.

# Error handling

## Quick diagnosis

Use this decision tree to find the right page for your issue:

```mermaid theme={null}
flowchart TD
    A["Error encountered"] --> B{"Where did it happen?"}
    B -->|API response| C{"HTTP status code?"}
    B -->|Webhook delivery| D["Webhook troubleshooting"]
    B -->|Search stuck / SLA| E["SLA and escalation"]
    C -->|401| F["Authentication troubleshooting"]
    C -->|400| G["Validation errors"]
    C -->|404 or 200 with error body| H["Resource not found"]
    C -->|5xx| I["Retry with backoff"]
    D --> D1["Webhook Integration"]
    E --> E1["SLA and escalation"]
    F --> F1["Authentication"]
    G --> G1["Troubleshooting"]
    H --> H1["Errors reference"]
    I --> I1["Errors reference"]
```

## Detailed guides

| Topic                                              | Page                                                                                |
| -------------------------------------------------- | ----------------------------------------------------------------------------------- |
| HTTP status codes, error bodies, client retries    | [Errors](/api-reference/errors)                                                     |
| Search SLAs, terminal conditions, human escalation | [SLA and escalation](/guides/sla-and-escalation)                                    |
| Common validation and integration issues           | [Troubleshooting](/troubleshooting)                                                 |
| Auth failures                                      | [Authentication — Troubleshooting](/getting-started/authentication#troubleshooting) |
| Webhook delivery problems                          | [Webhook Integration — Troubleshooting](/webhooks/integration#troubleshooting)      |

## Error response shape

All API errors return a consistent JSON body:

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}
```

The `message` field may be a string or an array of strings (for multi-field validation failures). Always handle both cases in your client code. See [Errors](/api-reference/errors) for the full reference.

## Retry decision matrix

| Scenario                       | Retry?    | Strategy                                  |
| ------------------------------ | --------- | ----------------------------------------- |
| `5xx` or network timeout       | Yes       | Exponential backoff (2^attempt seconds)   |
| `400` validation error         | No        | Fix the request body                      |
| `401` authentication error     | No        | Refresh or request a new JWT              |
| Order create with no response  | Maybe     | Reconcile by `externalSearchId` first     |
| Webhook handler returned `5xx` | Automatic | SNH AI retries per `retryAttempts` config |