Manejo de errores

La API de Genius Checkout usa códigos de estado HTTP estándar. Los cuerpos de error son siempre JSON con un único campo error.

Códigos de estado

Código HTTP	Significado
200	Éxito
201	Creado (reembolso, suscripción, etc.)
401	Clave API inválida o ausente
403	Operación cross-mode — una clave gc_test_ intentó tocar datos live, o viceversa
404	Recurso no encontrado
409	Conflicto de idempotencia — ver abajo
422	Error de validación o pago rechazado
429	Límite de tasa excedido — ver Límites de tasa
500	Error del servidor — reintenta con backoff, contacta soporte si persiste

Cuerpo del error

El envoltorio estándar es un único string error:

{ "error": "Mensaje de error legible" }

Para fallos de pago, el mensaje incluye el motivo de rechazo del gateway cuando está disponible.

Errores de validación (422)

Para validación a nivel de controller (p. ej. amount ausente, moneda no soportada, token no encontrado, token de suscripción inactivo), el cuerpo es el envelope estándar { "error": ... }.

Para la validación field-level por defecto de Laravel (la ruta estándar validate()), el cuerpo es la forma estructurada del framework:

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": ["The amount field is required."],
    "currency": ["The currency must be 3 characters."]
  }
}

Siempre revisa ambas formas. Si errors está presente, expone los mensajes por campo en tu UI; si no, usa error.

Causas comunes de 422:

• amount no es entero o falta
• currency no está en la lista soportada (ver Monedas)
• success_url / failure_url no son URLs absolutas
• tax_amount no concilia con subtotal y amount
• El token no está active
• Un pago rechazado (ver abajo)

Pagos rechazados (422)

Un pago rechazado devuelve 422 con un mensaje seguro para mostrar al cliente. La respuesta completa del gateway (código ISO, AVS, CVV) se registra en el panel del comerciante para inspección — nunca se devuelve a la llamada API. Ver Códigos de rechazo para el mapeo al mensaje del comprador.

Conflictos de idempotencia (409)

Cuando reenvías una solicitud con el mismo Idempotency-Key pero un cuerpo distinto, la plataforma se niega a sobrescribir la original — ese es el sentido de la idempotencia. Dos sabores de 409:

{ "error": "Idempotency key already used with different request parameters." }

{ "error": "Request is still being processed. Please retry later." }

El primero significa: la clave ya se usó para otro cuerpo — usa una nueva clave o envía el cuerpo original. El segundo: la solicitud original sigue en vuelo (ventana de lock de 30 segundos) — espera brevemente y reintenta. Tras completarse, los reintentos con el mismo cuerpo devuelven la respuesta cacheada.

Cross-mode (403)

Las claves gc_test_ y gc_live_ están estrictamente aisladas en el servidor. Una clave test no puede leer, cobrar, reembolsar, suscribir ni revocar un token / transacción / cliente live (y viceversa). Solicitudes mixtas devuelven:

{ "error": "Cross-mode operation not permitted." }

Elegir la clave equivocada para el entorno es la causa habitual — revisa tu encabezado Authorization.

Límites de tasa (429)

Los límites por defecto son generosos y por clave. Ver Límites de tasa para la tabla completa, encabezados de respuesta y guía de backoff.

Reintentos

• 5xx y 429 son seguros de reintentar. Usa backoff exponencial — 1s, 2s, 4s, 8s, etc.
• 4xx (excepto 429) no es seguro reintentar tal cual. Corrige la solicitud primero.
• Para solicitudes mutadoras (crear sesión, cobrar token, reembolsar), incluye un encabezado Idempotency-Key. Los reintentos devuelven la respuesta original — sin doble cobro. Mira Autenticación → Idempotencia.