Gestion des erreurs

L'API Genius Checkout utilise les codes HTTP standard. Les corps d'erreur sont toujours du JSON avec un seul champ error.

Codes de statut

Code HTTP	Signification
200	Succès
201	Créé (remboursement, abonnement, etc.)
401	Clé API invalide ou manquante
403	Opération cross-mode — une clé gc_test_ a tenté de toucher des données live, ou inversement
404	Ressource introuvable
409	Conflit d'idempotence — voir plus bas
422	Erreur de validation ou paiement refusé
429	Limite de requêtes dépassée — voir Limites de débit
500	Erreur serveur — ré-essayer en backoff, contacter support si persistant

Corps de l'erreur

L'enveloppe standard est une seule chaîne error :

{ "error": "Message d'erreur lisible" }

Pour les échecs de paiement, le message inclut la raison du refus de la passerelle quand disponible.

Erreurs de validation (422)

Pour la validation au niveau contrôleur (p. ex. amount manquant, devise non supportée, token introuvable, token d'abonnement inactif), le corps est l'enveloppe standard { "error": ... }.

Pour la validation field-level par défaut de Laravel (le chemin validate() standard), le corps est la forme structurée du framework :

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

Vérifiez toujours les deux formes. Si errors est présent, remontez les messages par champ dans votre UI ; sinon, repli sur error.

Causes courantes de 422 :

• amount n'est pas un entier ou manque
• currency ne fait pas partie des devises supportées (voir Devises)
• success_url / failure_url ne sont pas des URLs absolues
• tax_amount ne se réconcilie pas avec subtotal et amount
• Le token n'est pas active
• Un paiement refusé (voir ci-dessous)

Refus de paiement (422)

Un paiement refusé renvoie 422 avec un message présentable au client. La réponse complète de la passerelle (code ISO, AVS, CVV) est journalisée sur le tableau de bord marchand pour inspection — jamais renvoyée à l'appelant API. Voir Codes de refus pour le mapping du message acheteur.

Conflits d'idempotence (409)

Quand vous renvoyez une requête avec la même Idempotency-Key mais un corps différent, la plateforme refuse d'écraser l'originale — c'est tout l'intérêt de l'idempotence. Deux variantes de 409 :

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

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

Le premier signifie : la clé a déjà été utilisée pour un autre corps — utilisez une nouvelle clé, ou envoyez le corps original. Le second : la requête originale est toujours en vol (fenêtre de lock de 30 secondes) — patientez puis ré-essayez. Après que l'originale se termine, les rejeux avec le même corps renvoient la réponse mise en cache.

Cross-mode (403)

Les clés gc_test_ et gc_live_ sont strictement cloisonnées côté serveur. Une clé test ne peut pas lire, débiter, rembourser, abonner ni révoquer un token / une transaction / un client live (et inversement). Les requêtes croisées renvoient :

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

Choisir la mauvaise clé pour l'environnement est la cause habituelle — vérifiez votre en-tête Authorization.

Limites de requêtes (429)

Les limites par défaut sont généreuses et par clé. Voir Limites de débit pour la table complète, les en-têtes de réponse et le conseil de backoff.

Relances

• 5xx et 429 sont sûrs à ré-essayer. Backoff exponentiel — 1s, 2s, 4s, 8s, etc.
• 4xx (hors 429) ne sont pas sûrs à ré-essayer tels quels. Corrigez la requête d'abord.
• Pour les requêtes mutantes (créer une session, facturer un token, rembourser), incluez un en-tête Idempotency-Key. Les ré-envois renvoient la réponse originale — pas de double paiement. Voir Authentification → Idempotence.