Lueira — Software de gestión para turismo activo

Gestión de errores

Todos los errores devuelven un cuerpo JSON consistente, independientemente del endpoint.

Formato

  • error_code — código estable que puedes usar para manejar el error programáticamente.
  • message — descripción legible del error.
  • errors — opcional; detalle por campo en errores de validación.
shell
{
  "error_code": "VALIDATION_ERROR",
  "message": "El campo \"email\" es obligatorio",
  "errors": {
    "email": "required"
  }
}

Códigos de estado

EstadoSignificado
400Petición inválida (validación de campos)
401Clave ausente, inválida o revocada
402Suscripción sin acceso o cuota mensual agotada sin ampliación automática
403La clave no tiene el scope necesario
404El recurso no existe (o no pertenece a tu tenant)
409Conflicto — el recurso ya existe o el estado no lo permite
422Regla de negocio incumplida (p. ej. sin disponibilidad)
429Límite de peticiones excedido — ver Límites
500Error interno; reintenta más tarde

Estrategia de reintentos

Reintenta con espera exponencial ante 429, 502, 503 y 504. No reintentes automáticamente ante 4xx distintos de 429: son errores de tu petición y se repetirán igual.

Errores de la API pública de tienda

La API de tienda usa un contrato distinto al de la API de administración. Todas sus respuestas de error tienen este formato:

  • 400 invalid_request — solicitud, JSON o parámetros no válidos.
  • 401 invalid_api_key, invalid_customer_token o customer_authentication_required — falta una credencial válida.
  • 402 store_api_subscription_required — suscripción de API inactiva o no disponible.
  • 403 insufficient_scope, api_key_type_not_permitted o forbidden — tipo de clave, scope o permiso insuficiente.
  • 404 not_found o store_not_found — API desactivada, tienda o recurso no disponible.
  • 409 idempotency_conflict o commerce_conflict — conflicto de idempotencia o estado de compra incompatible; una operación pendiente requiere conciliación.
  • 410 cart_link_expired — enlace de carrito caducado.
  • 422 invalid_selection — selección de producto o disponibilidad no válida.
  • 429 rate_limit_exceeded — límite por minuto alcanzado; respeta Retry-After.
  • 503 *_unavailable — servicio dependiente no disponible.
  • 500 store_api_error — error interno inesperado; contacta con soporte e incluye el request_id.
shell
{"error":{"code":"invalid_request","request_id":"..."}}
En operaciones de compra, no reintentes a ciegas un 409: una operación pendiente puede haber creado una reserva o iniciado un pago. Conserva el mismo Idempotency-Key y consulta el estado antes de reintentar.