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

# Errores

> Formato problem+json y tabla de códigos estables para manejar (y auto-corregir) errores.

Cuando algo sale mal, la API responde con el status HTTP apropiado y un cuerpo
**`application/problem+json`** (RFC 9457 / 7807):

```json theme={null}
{
  "type": "https://finzaria.com/problems/split-amount-mismatch",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "La suma de las partes (450.00) no cuadra con el monto total (500.00).",
  "code": "SPLIT_AMOUNT_MISMATCH"
}
```

| Campo    | Para qué sirve                                                                              |
| -------- | ------------------------------------------------------------------------------------------- |
| `code`   | **Identificador estable** — programa contra este, no contra el texto.                       |
| `detail` | Mensaje accionable en es-MX; sirve para mostrar al usuario o para que un agente se corrija. |
| `status` | El código HTTP (mismo que la respuesta).                                                    |
| `title`  | Nombre corto del tipo de error.                                                             |
| `type`   | URI del tipo (documental).                                                                  |

<Tip>
  Los `detail` están escritos para ser **auto-corregibles**: un LLM que recibe el error suele poder
  arreglar el request y reintentar sin intervención humana.
</Tip>

## Familias de status

| Status | Significado                                             | Qué hacer                                                                        |
| ------ | ------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `400`  | Request malformado                                      | Revisa el JSON y los tipos.                                                      |
| `401`  | Falta o es inválido el token                            | Manda un `Authorization: Bearer` válido ([auth](/guias/autenticacion/api-keys)). |
| `403`  | Sin permiso (p. ej. key `read_only` escribiendo)        | Usa una credencial con permiso ([scopes](/guias/autenticacion/scopes)).          |
| `404`  | No existe (o no es tuyo)                                | Verifica el `id`.                                                                |
| `409`  | Conflicto (p. ej. borrar algo con dependencias)         | Resuelve la dependencia que indica `detail`.                                     |
| `422`  | Válido pero no procesable (reglas de negocio)           | Corrige según `detail` (montos, fechas, etc.).                                   |
| `429`  | [Rate limit](/guias/referencia-transversal/rate-limits) | Espera y reintenta con backoff.                                                  |
| `5xx`  | Error nuestro                                           | Reintenta con backoff; si persiste, repórtalo.                                   |

## Códigos comunes

Cada error trae un `code` estable. Algunos ejemplos:

| `code`                  | Status | Causa → arreglo                                     |
| ----------------------- | ------ | --------------------------------------------------- |
| `AUTH_MISSING_TOKEN`    | 401    | Falta el header → manda `Authorization: Bearer …`.  |
| `AUTH_INVALID_TOKEN`    | 401    | Key/token inválido o revocado → usa uno vigente.    |
| `API_KEY_READ_ONLY`     | 403    | Key de solo lectura escribiendo → usa `read_write`. |
| `SPLIT_AMOUNT_MISMATCH` | 422    | Las partes no suman el total → ajústalas.           |

<Note>
  La lista completa y actualizada de códigos vive en cada endpoint de la
  [Referencia de API](/referencia). Trátalos como contrato estable.
</Note>