Name: Nuvlyx
Rating: 4.9 (124 reviews)

Formato de respuesta de error

Todas las respuestas de error usan el mismo cuerpo JSON, independientemente del endpoint:

{
  "statusCode": 403,
  "message": "Este token no tiene los permisos requeridos: orders:write",
  "error": "Forbidden"
}

El campo message está en español y va dirigido al integrador. Para errores de validación (422) message puede ser un arreglo de strings, uno por campo inválido.

Códigos HTTP que devuelve la API

Código	Significado	¿Reintentar?
`200`	Éxito.	—
`201`	Recurso creado.	—
`400`	Petición mal formada o regla de negocio violada (ej: saldo insuficiente).	No (corrija primero).
`401`	Token faltante, mal formado, revocado o expirado.	No (regenere token).
`403`	Token válido pero sin scopes para la ruta.	No (agregue scope).
`404`	Recurso no encontrado en su tienda.	No.
`409`	Conflicto (ej: URL de webhook duplicada).	No.
`422`	Validación falló (campo requerido faltante, formato inválido).	No (corrija el cuerpo).
`429`	Rate limit excedido (ver rate limits).	Sí, con backoff.
`500`	Error interno inesperado.	Sí, con backoff exponencial.
`502 / 503 / 504`	Servicio temporalmente no disponible.	Sí, con backoff exponencial.

Ejemplos comunes

Saldo insuficiente al crear un pedido

HTTP/1.1 400 Bad Request
{
  "statusCode": 400,
  "message": "Saldo insuficiente en el monedero del cliente.",
  "error": "Bad Request"
}

Cliente sin WhatsApp vinculado

HTTP/1.1 404 Not Found
{
  "statusCode": 404,
  "message": "No se encontró un cliente con ese teléfono vinculado. El cliente debe vincular su WhatsApp desde su perfil en la tienda.",
  "error": "Not Found"
}

Validación de campos

HTTP/1.1 422 Unprocessable Entity
{
  "statusCode": 422,
  "message": [
    "amount must not be less than 1",
    "items must contain at least 1 element"
  ],
  "error": "Unprocessable Entity"
}

Estrategia de reintentos recomendada

4xx: no reintente. Corrija la petición primero.
429: respete el header Retry-After si está presente, o use backoff exponencial empezando en 1 s.
5xx: backoff exponencial — 1 s, 2 s, 4 s, 8 s, 16 s — máximo 5 intentos.
Use Idempotency-Key al crear pedidos y recargas para evitar duplicados en reintentos.

Manejo de errores y códigos HTTP