Errores
Los códigos de estado que devuelve la API, la forma del cuerpo de error y qué hacer con cada caso.
Cuando algo sale mal, la API responde con un código de estado HTTP y un cuerpo con un solo campo:
{
"message": "Client not found"
}El message es un texto para el desarrollador, no para mostrarle al usuario:
puede cambiar sin aviso. Lo que conviene mirar en el código es el código de
estado.
Códigos de estado
| Código | Qué significa | Qué hacer |
|---|---|---|
200 | Salió bien. | — |
201 | Se creó el recurso. Lo devuelven los dos endpoints de Consumos. | — |
400 | El pedido no se pudo procesar: el beneficio ya se usó, no está vigente, o al usuario no le alcanzan los puntos. | Leer el message para saber cuál de los casos es. No reintentar igual. |
401 | La credencial falta, venció o no sirve para este endpoint. | Con API key, revisar que sea la correcta. Con token de usuario, renovarlo. |
403 | El cliente existe pero no puede tener consumos. | No reintentar. |
404 | El recurso no existe: cliente, beneficio o comercio. | Revisar el código o el id que mandaste. |
422 | El cuerpo o los headers no pasaron la validación. | Ver Errores de validación. |
Errores de validación
El 422 es distinto a los demás: no trae message sino un detail con la lista
de todo lo que está mal, un item por campo.
{
"detail": [
{
"loc": ["body", "amount"],
"msg": "Input should be a valid integer",
"type": "int_parsing"
}
]
}Cada item de detail
locarrayrequeridoDónde está el problema. El primer elemento dice en qué parte del pedido
(body, query, header, path) y el resto es el camino hasta el campo.
msgstringrequeridoQué tiene de malo.
typestringrequeridoEl tipo de error de validación.
La causa más frecuente de un 422 no es el cuerpo: es el header
X-Commerce-Id que falta. Es obligatorio en todos los endpoints de
Autenticación,
Mi cuenta y Público.
Dos casos que no son errores
Pedir un código siempre responde 200
POST /v1/auth/otp/request
responde 200 incluso si el email no tiene cuenta en Loybox. Es a propósito:
si respondiera distinto, cualquiera podría usar el endpoint para averiguar qué
emails están registrados. No lo uses para validar si un usuario existe.
Sin nivel asignado es un 404
GET /v1/me/level devuelve 404 cuando el
usuario todavía no tiene nivel, o cuando el comercio no usa niveles. Es el caso
normal de un cliente nuevo, no una falla: en la UI corresponde esconder la
sección de niveles, no mostrar un error.
Reintentos
Comprar un beneficio mueve puntos, así que un reintento a ciegas puede cobrarlos
dos veces. Para eso
POST /v1/me/benefits/exchange
acepta el header Idempotency-Key: si mandás el mismo valor otra vez, la compra
no se repite.
Idempotency-Key: 8f14e45f-ea0f-4d1c-9a1b-2c3d4e5f6a7bUsá un valor distinto por cada compra que el usuario inicia (un UUID alcanza) y el mismo en todos los reintentos de esa compra.