Cuando algo sale mal, la API responde con el status HTTP apropiado y un cuerpo
application/problem+json (RFC 9457 / 7807):
| 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). |
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.
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). |
403 | Sin permiso (p. ej. key read_only escribiendo) | Usa una credencial con permiso (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 | 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. |
La lista completa y actualizada de códigos vive en cada endpoint de la
Referencia de API. Trátalos como contrato estable. 
