> ## 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.

# Manejo de errores

> Códigos de estado HTTP y formato de respuesta de error.

## Códigos de estado HTTP

| Código | Descripción                                                                             |
| ------ | --------------------------------------------------------------------------------------- |
| `200`  | Éxito.                                                                                  |
| `400`  | Petición incorrecta — descarga de documento fallida o URL inválida.                     |
| `401`  | No autorizado — API key inválida o faltante.                                            |
| `402`  | Créditos insuficientes — recarga tu saldo para continuar.                               |
| `404`  | No encontrado — el deployment, entry o batch no existe.                                 |
| `422`  | Error de validación — cuerpo de petición o formato de documento inválido.               |
| `503`  | Servicio temporalmente no disponible por alta carga. Reintenta con backoff exponencial. |

## Formato de respuesta de error

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

| Campo     | Tipo          | Descripción                                |
| --------- | ------------- | ------------------------------------------ |
| `error`   | string        | Código de error legible por máquina.       |
| `message` | string        | Descripción legible por humanos.           |
| `details` | object o null | Contexto adicional cuando esté disponible. |

## Errores de procesamiento vs. errores de API

* **Errores de API** (4xx): la petición falló. No se procesó ningún documento.
* **Errores de procesamiento** (en el campo `errors` de una respuesta `200`): el documento se procesó pero algunos campos no pudieron extraerse o validarse.

Una respuesta con `status: "completed_with_errors"` sigue siendo un `200 OK`:

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

## Estrategia de reintentos

Para respuestas `503` (alta carga), implementa backoff exponencial:

```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("Máximo de reintentos excedido")
```