Doku

Tippe ein Stichwort. Mit Esc schließt du die Suche.
EN
Anmelden Kostenlos starten
Entwickler/Grundlagen

Einen Schreibzugriff wiederholen, einmal ausführen.

Sende bei einem POST oder PATCH einen Idempotency-Key mit. Bricht die Verbindung ab und du schickst dieselbe Anfrage noch einmal, gibt up4 die erste Antwort zurück, statt einen zweiten Monitor anzulegen.

Den Header nutzen

KEY=$(uuidgen)

curl -si -X POST https://app.upfour.io/v1/monitors \
  -H "Authorization: Bearer $UP4_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"name":"Example","url":"https://example.com","monitor_type":"http"}' \
  | grep -i -E '^(HTTP|idempotency-status)'
HTTP/2 201
idempotency-status: stored

Führe denselben Befehl mit demselben KEY noch einmal aus:

HTTP/2 201
idempotency-status: replayed

Die Regeln

ThemaVerhalten
HeaderIdempotency-Key, ein beliebiger nicht leerer Text. Eine UUID ist eine gute Wahl. Ein leerer oder fehlender Header schaltet die Funktion für diese Anfrage ab.
MethodenPOST und PATCH. PUT, DELETE und GET ignorieren den Header.
Nicht erfasstPOST /monitors/batch nutzt diese Schicht nicht. Es verlangt den Header und führt eine eigene Quittung (gleicher Schlüssel und Body: die gespeicherte Quittung, anderer Body: eine Ablehnung).
PflichtPOST /incidents/{incidentID}/escalate und POST /escalation-policies/{policyID}/test antworten ohne den Header mit 400 und nehmen höchstens 128 Zeichen an. Überall sonst ist er freiwillig und ohne Längengrenze.
Ein Schlüssel gehört zuDeinem Unternehmen, deinem Benutzer, Methode und Pfad der Anfrage (ohne Query-String) und dem Text des Schlüssels. Derselbe Schlüssel auf einem anderen Pfad ist ein anderer Schlüssel.
Vergleich des BodyJSON-Bodys werden als JSON verglichen, Leerraum und Reihenfolge der Schlüssel spielen also keine Rolle. Andere Bodys werden Byte für Byte verglichen.
Gespeichert für24 Stunden nach der ersten Antwort, danach wird die Quittung gelöscht. Der Schlüssel ist dann wieder frei: Die nächste Anfrage damit läuft, und ihre Antwort wird neu gespeichert.
Was gespeichert wirdAntworten mit Status 200 bis 499 und JSON-Body, auch Validierungsfehler. Nicht gespeichert werden 5xx und Antworten ohne Body.
SecretsDie Antwort wird so gespeichert, wie sie gesendet wurde. Eine Wiederholung von POST /webhook-subscriptions oder POST /webhook-subscriptions/{id}/rotate-secret enthält deshalb innerhalb dieser 24 Stunden dasselbe einmalige secret, auch wenn eine spätere Rotation es ungültig gemacht hat. Siehe Signier-Secret abrufen.
WiederholungenLiefern gespeicherten Status, Content-Type und Body mit Idempotency-Status: replayed.
RatenlimitsEine Wiederholung zählt als Anfrage.

Was du bekommst

SituationErgebnis
Keine Quittung zum SchlüsselDie Anfrage läuft. Eine Antwort mit Status 200 bis 499 und JSON-Body wird gespeichert und trägt Idempotency-Status: stored.
Quittung, gleicher BodyGespeicherter Status und Body kommen mit Idempotency-Status: replayed zurück. Die Anfrage läuft nicht noch einmal.
Quittung, anderer Body409 idempotency_key_conflict. details.original_request_at nennt den Zeitpunkt der ersten Anfrage.
Quittung, aber mit einem anderen API-Schlüssel oder unter geändertem Zugriff entstanden409 idempotency_replay_unavailable. Die Anfrage läuft nicht noch einmal.
Antwort war 5xx, 204 oder hatte keinen JSON-BodyNichts wird gespeichert. Ein neuer Versuch mit demselben Schlüssel führt die Anfrage erneut aus.
 
{
  "error": {
    "code": "idempotency_key_conflict",
    "message": "Idempotency key was already used with a different request body",
    "request_id": "req_…",
    "details": { "original_request_at": "2026-10-27T09:14:02Z" }
  }
}

Die Quittung merkt sich, wer die Anfrage gesendet hat: den API-Schlüssel, seine Scopes und seine Zugriffsstufe sowie seinen Zugriff auf Kunden. Ein neuer Versuch mit einem anderen Schlüssel oder nachdem sich eines davon geändert hat, bekommt idempotency_replay_unavailable statt einer Wiederholung, und die Anfrage läuft nicht noch einmal. Schau dir die Ressource an, um zu sehen, was passiert ist.

Typische Fehler

  • Bei jedem neuen Versuch ein neuer Schlüssel. Erzeuge den Schlüssel einmal pro gewünschter Operation und verwende ihn für jeden Versuch dieser Operation weiter.
  • Ein Schlüssel für verschiedene Operationen. Der zweite Body bekommt 409 idempotency_key_conflict. Nimm einen Schlüssel pro Operation.
  • Eine abgelehnte Anfrage unter demselben Schlüssel korrigieren. Auch ein 400 wird gespeichert. Sendest du denselben Body erneut, kommt das 400 noch einmal; sendest du einen korrigierten Body, ist das ein Konflikt. Nimm für die korrigierte Anfrage einen neuen Schlüssel.
  • Wiederholen, während die erste Anfrage noch läuft. Die Quittung wird geschrieben, wenn die erste Anfrage fertig ist, eine überlappende Wiederholung wird also nicht sicher abgefangen. Warte auf die Antwort oder dein Timeout.
  • Für den neuen Versuch einen anderen API-Schlüssel nehmen. Siehe idempotency_replay_unavailable oben.
  • Sich bei DELETE oder PUT darauf verlassen. Der Header wird bei diesen Methoden ignoriert.
Volle Größe ↗