Un error de la API llega siempre en el mismo documento: un arreglo errors y un objeto meta. La estructura general se describe en la forma de las respuestas; esta página cubre el contenido de cada entrada de error y cómo tratarlo.
El inventario completo de códigos, con su significado uno por uno, está en la taxonomía de errores.
Campos de una entrada
{
"errors": [
{
"status": "422",
"code": "phone_not_verified",
"detail": "El teléfono no está verificado.",
"source": { "pointer": "/data/attributes/phone" },
"meta": { "masked_phone": "+52 55 ••••1234" }
}
],
"meta": {
"version": "1.57.0",
"api_version": "v1",
"request_id": "a1b2c3d4e5f6",
"datetime": { "timezone": "UTC", "format": "ISO 8601" }
}
}| campo | presencia | contenido |
|---|---|---|
code | Siempre | Identificador estable en snake_case. Es el único campo sobre el que debe ramificar una integración |
status | Siempre | El código HTTP repetido como cadena, para que un error conserve su categoría al procesarse fuera de la respuesta |
detail | Siempre | Texto legible. Se traduce según la cabecera Accept-Language (es / en) |
source.pointer | Opcional | Campo del cuerpo que causó el rechazo, como JSON Pointer (RFC 6901) |
meta | Opcional | Contexto adicional del rechazo: masked_phone, retry_after_seconds, limit |
Qué es estable y qué no
El code no cambia ni se traduce: es el contrato. El detail cambia con el idioma y puede reformularse entre versiones sin previo aviso, porque es texto para leer, no para comparar.
Una integración que ramifica sobre detail funciona hasta que alguien solicita el otro idioma o hasta que una frase se reescribe. Es el error más frecuente al consumir esta API, y el más silencioso: no falla en pruebas, falla en producción.
Varios errores en una respuesta
Un 422 de validación devuelve una entrada por campo inválido, cada una con su propio source.pointer:
"errors": [
{ "status": "422", "code": "required", "detail": "El campo fecha es obligatorio.",
"source": { "pointer": "/data/attributes/fecha" } },
{ "status": "422", "code": "invalid_clabe_checksum", "detail": "El dígito de control no coincide.",
"source": { "pointer": "/data/attributes/cuenta_beneficiaria" } }
]El recorrido correcto es sobre todo el arreglo. Leer únicamente errors[0] oculta el resto de los campos que hay que corregir, y obliga a un ciclo de reintentos que la respuesta ya había resuelto en uno.
Significado de cada código HTTP
| status | significado en esta API |
|---|---|
400 | Petición malformada: JSON inválido, parámetro ausente, formato incorrecto |
401 | Falta autenticación o las credenciales no son válidas |
403 | Autenticado, pero sin permiso para ese recurso o acción |
404 | El recurso no existe o no es visible para la cuenta |
405 | Ruta correcta con método HTTP equivocado |
409 | Conflicto de estado: idempotencia en curso, o recurso ya en estado terminal |
410 | El recurso existió y fue eliminado |
413 | El cuerpo supera el tope de la operación |
422 | La petición se recibió correctamente pero falló una validación de negocio |
429 | Se superaron los límites de tasa |
500 | Fallo inesperado del servidor |
502 | Un servicio externo —habitualmente Banxico— no responde o devuelve algo malformado |
503 | Subsistema temporalmente desactivado o sobrecargado |
Los 5xx y el 429 admiten reintento; el 4xx restante no, porque la petición debe corregirse antes de repetirse.
Diagnóstico
Cada respuesta de error incluye meta.request_id. Ese valor identifica la petición concreta en los registros del sistema y es el dato que hace falta para investigar un caso puntual.