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

# Error handling

> HTTP status codes and error response format.

## HTTP status codes

| Status | Description                                                                       |
| ------ | --------------------------------------------------------------------------------- |
| `200`  | Success.                                                                          |
| `400`  | Bad request — document download failed or invalid URL.                            |
| `401`  | Unauthorized — invalid or missing API key.                                        |
| `402`  | Insufficient credits — top up your balance to continue.                           |
| `404`  | Not found — deployment, entry, or batch doesn't exist.                            |
| `422`  | Validation error — invalid request body or document format.                       |
| `503`  | Service temporarily unavailable due to high load. Retry with exponential backoff. |

## Error response format

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "DEPLOYMENT_NOT_FOUND",
  "message": "Deployment not found",
  "details": null
}
```

| Field     | Type           | Description                        |
| --------- | -------------- | ---------------------------------- |
| `error`   | string         | Machine-readable error code.       |
| `message` | string         | Human-readable description.        |
| `details` | object or null | Additional context when available. |

## Processing errors vs. API errors

* **API errors** (4xx): the request itself failed. No document was processed.
* **Processing errors** (in the `errors` field of a `200` response): the document was processed but some fields couldn't be extracted or validated.

A response with `status: "completed_with_errors"` is still a `200 OK`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {"invoice_number": "INV-001", "total": null},
  "errors": [{"path": "/total", "message": "Required field missing", "code": "REQUIRED_FIELD"}],
  "status": "completed_with_errors"
}
```

## Retry strategy

For `503` (high load) responses, implement exponential backoff:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import time
import requests

def process_with_retry(deployment_id, documents, api_key, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            f"https://api.matil.ai/v3/deployments/{deployment_id}",
            headers={"x-api-key": api_key},
            json={"documents": documents}
        )
        if response.status_code == 503:
            time.sleep(2 ** attempt)
            continue
        return response.json()
    raise Exception("Max retries exceeded")
```