Aller au contenu
StampyWalletDocs
API et webhooks / Commencer / Erreurs

Erreurs et réessais

Le format des erreurs de l'API, tous leurs codes, et l'en-tête Idempotency-Key pour réessayer un POST sans risque de doublon.

Le format d'une erreur

Une erreur répond avec un statut HTTP 4xx ou 5xx et toujours le même corps :

Réponse d'erreur
{
  "erreur": {
    "code": "client_introuvable",
    "message": "Aucun client ne correspond dans ce commerce."
  }
}
  • code est stable : c'est lui que votre programme doit tester.
  • message est une phrase lisible, pour vos journaux. Son texte peut changer.

Les codes

StatutCodes
400requete_invalide (JSON illisible), client_requis, recherche_requise, montant_invalide, quantite_invalide, points_invalide, email_invalide, telephone_invalide, idempotency_key_invalide
401non_authentifie, cle_revoquee, signature_invalide (adresses d'entrée)
403formule_requise (l'API demande la formule Croissance), interdit
404introuvable (adresse), client_introuvable, passage_introuvable
409trop_tot, pas_dernier, deja_annule, recompense_offerte, aucune_recompense, requete_en_cours
422conditions_requises, montant_insuffisant
429trop_de_requetes (voir la limite de débit)
500interne : réessayez plus tard, avec la même Idempotency-Key

Réessayer sans doublon : Idempotency-Key

Un réseau qui coupe au mauvais moment, et vous ne savez pas si le passage a été enregistré. Pour réessayer sans risque, envoyez sur chaque POST (/clients, /passages, /recompenses) un en-tête Idempotency-Key : une valeur unique par opération, de 1 à 200 caractères, par exemple le numéro du ticket.

curl
curl https://app.stampywallet.com/v1/passages \
  -H "Authorization: Bearer sw_live_votre_cle" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-2026-10-25-0042" \
  -d '{"client": {"telephone": "+33612345678"}, "montant": 12.50}'
  • La réponse est gardée 24 heures. La même clé rejouée rend le même statut et le même corps, avec l'en-tête Idempotent-Replayed: true.
  • Une erreur 4xx est gardée aussi : la rejouer rend la même erreur. Une erreur 500 libère la clé, pour que vous puissiez réessayer.
  • Pendant que la première requête tourne encore : 409 requete_en_cours.

Astuce : sur POST /v1/passages, le champ reference (votre numéro de ticket) protège aussi : une même référence ne tamponne qu'une fois par commerce, même sans Idempotency-Key.

Mis à jour le

Cette page vous a aidé ?