# Fehler und Wiederholungen

> Für KI-Agenten: Das vollständige Verzeichnis der Dokumentation steht unter [llms.txt](https://stampywallet.com/de/docs/llms.txt), die gesamte Dokumentation passt in eine Datei: [llms-full.txt](https://stampywallet.com/de/docs/llms-full.txt). Seite online: https://stampywallet.com/de/docs/api/fehler/

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:

```json title="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

| 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](https://stampywallet.com/de/docs/api/authentifizierung/#limite)) |
| `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.

```bash title="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`](https://stampywallet.com/de/docs/api/besuch-erfassen/) schützt auch das Feld `reference` (Ihre Bonnummer): Dieselbe Referenz stempelt pro Geschäft nur einmal, auch ohne `Idempotency-Key`.
