Zum Inhalt springen

Für KI-Agenten: Das Verzeichnis der Dokumentation steht unter https://stampywallet.com/de/docs/llms.txt, die gesamte Dokumentation in einer Datei unter https://stampywallet.com/de/docs/llms-full.txt, und diese Seite gibt es als Markdown: https://stampywallet.com/de/docs/api/fehler.md (oder mit dem Header Accept: text/markdown).

StampyWalletDocs
API und Webhooks / Erste Schritte / FehlerAls Markdown ansehen

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:

Fehlerantwort
{
  "erreur": {
    "code": "client_introuvable",
    "message": "Kein passender Kunde in diesem Geschäft."
  }
}
  • code ist stabil: Diesen Wert sollte Ihr Programm prüfen.
  • message ist ein lesbarer Satz für Ihre Logs. Der Text kann sich ändern.

Die Codes

StatusCodes
400requete_invalide (JSON nicht lesbar), client_requis, recherche_requise, montant_invalide, quantite_invalide, points_invalide, email_invalide, telephone_invalide, idempotency_key_invalide
401non_authentifie, cle_revoquee, signature_invalide (Eingangsadressen)
403formule_requise (die API erfordert den Tarif Wachstum), 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 (siehe das Ratenlimit)
500interne: 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
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. Ein 500-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.

War diese Seite hilfreich?