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
| Estado | Significado |
|---|---|
| 400 | Petición inválida (validación de campos) |
| 401 | Clave ausente, inválida o revocada |
| 402 | Suscripción sin acceso o cuota mensual agotada sin ampliación automática |
| 403 | La clave no tiene el scope necesario |
| 404 | El recurso no existe (o no pertenece a tu tenant) |
| 409 | Conflicto — el recurso ya existe o el estado no lo permite |
| 422 | Regla de negocio incumplida (p. ej. sin disponibilidad) |
| 429 | Límite de peticiones excedido — ver Límites |
| 500 | Error 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_tokenocustomer_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_permittedoforbidden— tipo de clave, scope o permiso insuficiente.404 not_foundostore_not_found— API desactivada, tienda o recurso no disponible.409 idempotency_conflictocommerce_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; respetaRetry-After.503 *_unavailable— servicio dependiente no disponible.500 store_api_error— error interno inesperado; contacta con soporte e incluye elrequest_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.