Fehler und Wiederholungen
Das Fehlerformat der API, alle Fehlercodes und der Header Idempotency-Key, um einen POST ohne Risiko einer Dublette zu wiederholen.
Das Format eines Fehlers
Ein Fehler antwortet mit einem HTTP-Status 4xx oder 5xx und immer demselben Body:
{
"erreur": {
"code": "client_introuvable",
"message": "Kein passender Kunde in diesem Geschäft."
}
}codeist stabil: Diesen Wert sollte Ihr Programm prüfen.messageist ein lesbarer Satz für Ihre Logs. Der Text kann sich ändern.
Die Codes
| Status | Codes |
|---|---|
400 | requete_invalide (JSON nicht lesbar), client_requis, recherche_requise, montant_invalide, quantite_invalide, points_invalide, email_invalide, telephone_invalide, idempotency_key_invalide |
401 | non_authentifie, cle_revoquee, signature_invalide (Eingangsadressen) |
403 | formule_requise (die API erfordert den Tarif Wachstum), interdit |
404 | introuvable (Adresse), client_introuvable, passage_introuvable |
409 | trop_tot, pas_dernier, deja_annule, recompense_offerte, aucune_recompense, requete_en_cours |
422 | conditions_requises, montant_insuffisant |
429 | trop_de_requetes (siehe das Ratenlimit) |
500 | interne: Versuchen Sie es später erneut, mit demselben Idempotency-Key |
Wiederholen ohne Dublette: Idempotency-Key
Die Verbindung bricht im falschen Moment ab, und Sie wissen nicht, ob der Besuch gespeichert wurde. Um ohne Risiko erneut zu senden, schicken Sie bei jedem POST (/clients, /passages, /recompenses) einen Header Idempotency-Key mit: ein eindeutiger Wert pro Vorgang, 1 bis 200 Zeichen lang, zum Beispiel die Bonnummer.
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}'- Die Antwort wird 24 Stunden aufbewahrt. Derselbe Schlüssel noch einmal gesendet liefert denselben Status und denselben Body, mit dem Header
Idempotent-Replayed: true. - Ein
4xx-Fehler wird ebenfalls aufbewahrt: Eine Wiederholung liefert denselben Fehler. Ein500-Fehler gibt den Schlüssel frei, damit Sie es erneut versuchen können. - Solange die erste Anfrage noch läuft:
409 requete_en_cours.
Tipp : bei POST /v1/passages schützt auch das Feld reference (Ihre Bonnummer): Dieselbe Referenz stempelt pro Geschäft nur einmal, auch ohne Idempotency-Key.