Idempotenz
Wie der `Idempotency-Key`-Header verhindert, dass Retries auf instabilen Netzen doppelt abrechnen.
Warum es wichtig ist
Netzwerke fallen mitten in Requests aus. Wenn du POST /v1/activations sendest und die Verbindung abbricht, bevor du die Antwort siehst, weißt du nicht, ob die Aktivierung erstellt wurde. Ein naives Retry könnte zweimal abrechnen.
Der Idempotency-Key-Header löst das: sende denselben Key beim Retry, bekomme dasselbe Ergebnis.
Verwendung
Erzeuge eine UUID pro logischer Operation, sende sie bei jedem Retry derselben Operation:
KEY=$(uuidgen)
curl -X POST https://api.eveses.com/v1/activations \
-H "Authorization: Bearer $EVESES_API_KEY" \
-H "Idempotency-Key: $KEY" \
-d '{"country":"ua", "service":"telegram"}'
Wiederhole denselben Aufruf mit demselben Idempotency-Key — du erhältst die ursprüngliche Antwort. Keine zweite Aktivierung, keine zweite Abrechnung.
TTL
Keys werden 24 Stunden lang gemerkt. Danach wird der Slot freigegeben und derselbe Key kann als neuer wiederverwendet werden.
Wo es greift
Alle POST /v1/* Endpunkte, die erstellen oder abrechnen: Aktivierungen, Mieten, Einzahlungen, Verlängerungen. Read-Endpunkte (GET) sind bereits idempotent und ignorieren den Header.
Konflikte
Wenn du denselben Key mit anderem Body wiederverwendest, gibt die API 409 idempotency_conflict zurück. Halte den Body bei Retries identisch oder generiere einen neuen Key.
SDK-Verhalten
Offizielle SDKs generieren automatisch Idempotency-Keys für jeden Create-Aufruf und verwenden sie bei automatischen Retries wieder. Du kannst sie mit einem expliziten Key überschreiben.