# Errores (https://docs.loybox.com.ar/api-reference/errores)



Cuando algo sale mal, la API responde con un código de estado HTTP y un cuerpo
con un solo campo:

```json
{
  "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ódigos-de-estado]

| Código | Qué significa                                                                                                   | Qué hacer                                                                                                                |
| ------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `200`  | Salió bien.                                                                                                     | —                                                                                                                        |
| `201`  | Se creó el recurso. Lo devuelven los dos endpoints de [Consumos](https://docs.loybox.com.ar/api-reference/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](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token). |
| `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).                                                                     |

## 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.

```json
{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "Input should be a valid integer",
      "type": "int_parsing"
    }
  ]
}
```

<Fields title="Cada item de detail">
  <Field name="loc" type="array" required="true">
    Dó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.
  </Field>

  <Field name="msg" type="string" required="true">
    Qué tiene de malo.
  </Field>

  <Field name="type" type="string" required="true">
    El tipo de error de validación.
  </Field>
</Fields>

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](https://docs.loybox.com.ar/api-reference/autenticacion),
[Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta) y [Público](https://docs.loybox.com.ar/api-reference/publico).

## Dos casos que no son errores [#dos-casos-que-no-son-errores]

<Callout title="Pedir un código siempre responde 200">
  [`POST /v1/auth/otp/request`](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo)
  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.
</Callout>

<Callout title="Sin nivel asignado es un 404">
  [`GET /v1/me/level`](https://docs.loybox.com.ar/api-reference/mi-cuenta/nivel) 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.
</Callout>

## Reintentos [#reintentos]

Comprar un beneficio mueve puntos, así que un reintento a ciegas puede cobrarlos
dos veces. Para eso
[`POST /v1/me/benefits/exchange`](https://docs.loybox.com.ar/api-reference/mi-cuenta/comprar-beneficio)
acepta el header `Idempotency-Key`: si mandás el mismo valor otra vez, la compra
no se repite.

```
Idempotency-Key: 8f14e45f-ea0f-4d1c-9a1b-2c3d4e5f6a7b
```

Usá un valor distinto por cada compra que el usuario inicia (un UUID
alcanza) y el mismo en todos los reintentos de esa compra.