Envoltorio común
Los errores conocidos de API v1 se entregan bajo una propiedad errors con un arreglo de entradas.
{
"errors": [
{
"message": "<mensaje>"
}
]
}
Para validaciones, cada entrada identifica además el campo y la regla.
{
"errors": [
{
"message": "<mensaje generado por la validación>",
"rule": "<regla>",
"field": "<campo>"
}
]
}
Matriz de estados
| Estado | Significado operativo | Acción sugerida |
|---|---|---|
401 |
Falta la credencial, no es válida, expiró o fue revocada. | Revisa Authorization y el estado de la credencial en la plataforma. |
403 |
La credencial no tiene el permiso que exige la ruta. | Crea una credencial con el permiso correcto. |
404 |
El recurso no existe, es de otro tenant o :organization no es el de la credencial. |
No asumas que el identificador existe fuera de la organización. |
422 |
Query, body o identificador no cumple el contrato. | Corrige los campos usando field y rule. |
429 |
Demasiadas llamadas en el intervalo. | Reintenta con espera exponencial. |
Ejemplo 401
{
"errors": [{ "message": "La credencial API no es válida" }]
}
Ejemplo 403
{
"errors": [{ "message": "La credencial API no permite esta operación" }]
}
Ejemplo 404
{
"errors": [{ "message": "No se encontró el recurso solicitado" }]
}
Ejemplo 422 del identificador
{
"errors": [
{
"message": "El identificador del titular no es válido.",
"rule": "dataSubjectValue",
"field": "subjectValue"
}
]
}
Manejo recomendado
Usa curl --fail-with-body durante la integración para conservar el cuerpo de errores. En producción, registra código HTTP, ruta y un identificador interno de tu operación, pero evita guardar credenciales o identificadores de titulares en logs.