Guía de integración›Convenciones›Errores

Errores

Un error nunca es un texto suelto ni un JSON inventado por cada ruta. Es siempre un problem según el RFC 9457, con Content-Type: application/problem+json:

{
  "type": "validation_error",
  "title": "Validation error",
  "status": 400,
  "detail": "The request body has 1 invalid field.",
  "requestId": "req_01J9X0Y3A2B4C6D8E0F1G2H3J4",
  "errors": [{ "field": "identifier.value", "message": "Required" }]
}

type es el código estable: sobre él se programa. title y detail son para la persona que lee el registro y pueden cambiar de redacción.
requestId identifica la petición en nuestros registros. Es lo que soporte te va a pedir. Viene también en la cabecera X-Request-Id de toda respuesta, incluidas las buenas.
errors[] aparece sólo en los validation_error: un elemento por campo, con su ruta en notación de puntos.

Los tipos

type	status	Cuándo
`unauthorized`	401	Falta la llave, no tiene la forma esperada, está revocada o vencida.
`forbidden`	403	La llave no tiene el permiso que la operación exige.
`module_disabled`	403	La empresa no tiene habilitada la plataforma de cumplimiento.
`not_available_in_test_mode`	403	Una llave de prueba intentó escribir donde no existe modo de prueba.
`not_found`	404	El recurso no existe o no pertenece a tu empresa. Las dos cosas se ven igual a propósito.
`validation_error`	400	El cuerpo o los parámetros no cumplen el contrato; `errors[]` dice qué campo y por qué.
`conflict`	409	El estado actual no admite la operación (por ejemplo, sellar lo ya sellado).
`idempotency_key_reused`	422	El mismo `Idempotency-Key` llegó con un cuerpo distinto.
`rate_limited`	429	Más de 120 peticiones por minuto con la misma llave.
`unavailable`	503	Una dependencia no respondió. Reintenta con espera creciente.
`internal_error`	500	Algo nuestro falló. Manda el `requestId` a soporte.

Qué reintentar

Reintenta con espera creciente sólo los 429 (respetando Retry-After) y los 503. Un 4xx distinto no cambia por insistir: corrige la petición. Un 500 se reporta con su requestId.

Un caso frecuente: el id de otro recurso

Los ids llevan prefijo. Si mandas un tsk_… donde va un doc_…, no recibes un 404 ambiguo sino un 400 validation_error que dice qué mandaste y qué se esperaba, y la petición nunca llega a la base. Ver ids con prefijo.

Siguiente: Paginación →