Idempotenz: wiederholen, ohne doppelt auszustellen

Eine Rechnung muss genau einmal ausgestellt und zugestellt werden, auch wenn Ihre Verbindung abbricht. Senden Sie bei POST /invoices und POST /invoices/{id}/deliveries einen Idempotency-Key-Header (1 bis 200 sichtbare ASCII-Zeichen, z. B. eine UUID oder Ihre Auftragsnummer).

• Gleicher Schlüssel, gleicher Inhalt: Sie erhalten das ursprüngliche Ergebnis (200, Header Idempotent-Replayed: true). Nichts wird erneut ausgestellt oder versendet.
• Gleicher Schlüssel, anderer Inhalt: 422 idempotency.key-reused. Nutzen Sie für eine neue Rechnung einen neuen Schlüssel.
• Gleicher Schlüssel gleichzeitig: eine Anfrage gewinnt, die andere erhält 409 idempotency.conflict; wiederholen Sie sie.

Schlüssel werden 30 Tage aufbewahrt. Live- und Testschlüssel haben getrennte Schlüsselräume.

Wann wiederholen?

Wiederholen Sie mit demselben Schlüssel nach einer Zeitüberschreitung, einem Netzwerkfehler, 429 oder 503 (warten Sie Retry-After ab). Andere 4xx-Fehler außer 408, 409 idempotency.conflict und 429 wiederholen Sie nicht – korrigieren Sie die Anfrage.

Jede zufällige UUID eignet sich als Schlüssel; die SDKs bringen dafür eine Hilfsfunktion mit, sobald sie veröffentlicht sind. Auch Rechnungsnummern sind pro Verkäufer eindeutig: eine Nummer zweimal auszustellen ergibt 409 invoice.duplicate-number.