Errores y códigos HTTP¶
Las respuestas de error siguen una estructura distinta a las exitosas, pero conservan meta para trazabilidad.
Estructura¶
{
"error": {
"code": "INTERNAL_ERROR",
"details": [ ],
"message": "Ocurrió un error al obtener la factura con el id: 75510",
"httpStatus": 500,
"backendCode": null
},
"meta": {
"requestId": "ea9a86af-c2a2-4d47-afaf-7b20194859f6",
"timestamp": "2026-05-21T18:10:49Z",
"version": "v1"
}
}
| Campo | Uso |
|---|---|
error.code |
Código estable para ramificar en su código |
error.message |
Mensaje con la respuesta del error |
error.httpStatus |
Código HTTP de la respuesta |
error.details |
Lista opcional de detalles adicionales |
Códigos frecuentes¶
| HTTP | Código de error | Causa habitual |
|---|---|---|
| 400 | OK |
Respuesta exitosa |
| 400 | BAD_REQUEST |
Body o parámetros inválidos |
| 403 | UNAUTHORIZED |
API Key ausente o inválida |
| 401 | FORBIDDEN |
La API Key no tiene permiso para la ruta |
| 404 | NOT_FOUND |
Ruta no disponible o no existente |
| 429 | RATE_LIMIT_EXCEEDED |
Limite de peticiones excedido |
| 500 | INTERNAL_ERROR |
Error interno o regla de negocio no cumplida |
Errores de negocio¶
Cuando una regla no se cumple (registro no encontrado, validación de inventario, etc.), puede recibir 4xx o 5xx con mensaje descriptivo en error.message. Revise el mensaje y, si aplica, corrija los datos en su sistema antes de reintentar.