Errores - Finzaria

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

{
  "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).

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.