# Errores

Todos los errores devueltos por el API tienen el mismo schema:

```json
{ "message": "Texto descriptivo del error" }
```

## Códigos HTTP usados

| Código | Significado | Cuándo |
|---|---|---|
| `200` | OK | Operación exitosa. |
| `400` | Bad Request | RUT inválido (no calza el regex), nombre ausente o con formato inválido. |
| `402` | Payment Required | Saldo de créditos insuficiente para ejecutar la operación (`POST /api/check`, `POST /api/name-to-rut`, `POST /api/rut-to-name`). |
| `404` | Not Found | No se encontró persona o empresa para el RUT, o la búsqueda por nombre no arrojó resultados (incluye paginación fuera de rango). |

## Mensajes específicos por endpoint

| Endpoint | Código | `message` |
|---|---|---|
| `POST /api/check` | 400 | `Invalid RUT` |
| `POST /api/check` | 402 | `Insufficient balance` |
| `POST /api/check` | 404 | `No data found` |
| `GET /api/check/{rut}` | 400 | `Invalid RUT` |
| `GET /api/check/{rut}` | 404 | (sin Check para ese RUT en el mes calendario actual) |
| `POST /api/name-to-rut` | 400 | (nombre ausente o inválido) |
| `POST /api/name-to-rut` | 402 | `Insufficient balance` |
| `POST /api/name-to-rut` | 404 | `No data found` |
| `POST /api/rut-to-name` | 400 | `Invalid RUT` |
| `POST /api/rut-to-name` | 402 | `Insufficient balance` |
| `POST /api/rut-to-name` | 404 | `No data found` |

## Manejo recomendado

```python
import requests

def chapi_check(rut: str, token: str) -> dict | None:
    r = requests.post(
        "https://app.chapi.cl/api/check",
        headers={"Authorization": f"Token {token}"},
        json={"rut": rut},
        timeout=30,
    )
    if r.status_code == 200:
        return r.json()
    if r.status_code == 400:
        raise ValueError(f"RUT inválido: {rut}")
    if r.status_code == 402:
        raise RuntimeError("Saldo insuficiente — recarga créditos.")
    if r.status_code == 404:
        return None  # No hay datos para este RUT
    r.raise_for_status()
```

## Pendiente de aclaración

> **Rate limits.** No hay políticas de rate limit documentadas en el OpenAPI actual. No se especifica si existe `429 Too Many Requests` ni cuáles son los límites por token. Asume que un consumo razonable (decenas de requests por minuto) está permitido.

> **Reintentos seguros.** `GET /api/check/{rut}` es idempotente — reintentar es seguro. `POST /api/check` también es seguro de reintentar dentro del mismo mes calendario porque devuelve el Check existente sin generar uno nuevo. `POST /api/name-to-rut` y `POST /api/rut-to-name` son consultas (no mutaciones) y son seguras de reintentar.

> **5xx.** Manejo y semántica de errores `5xx` no está documentada. Asume política estándar: con un `503` o `504` vale la pena un reintento con backoff exponencial; con `500` reporta a soporte.

---

Última actualización: 2026-05-01