Idempotenz-Schlüssel

Netzwerke fallen aus. Läuft eine Anfrage in einen Timeout, weißt du nicht, ob die E-Mail angenommen wurde. Sende einen Idempotency-Key-Header und wiederhole beliebig oft: Derselbe Schlüssel mit demselben Body liefert die ursprüngliche Antwort und sendet die E-Mail nur einmal.

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.emails.send(
  { from: "Acme <hello@acme.com>", to: "user@example.com", subject: "Receipt", html: "<p>Thanks</p>" },
  { idempotencyKey: "receipt-order-1042" },
);

console.log(error ?? data);

curl -X POST https://api.spacepost.dev/emails \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" \
  -H "Idempotency-Key: receipt-order-1042" \
  -H "Content-Type: application/json" \
  -d '{ "from": "Acme <hello@acme.com>", "to": ["user@example.com"], "subject": "Receipt", "html": "<p>Thanks</p>" }'

requests.post(
    "https://api.spacepost.dev/emails",
    headers={
        "Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}",
        "Idempotency-Key": "receipt-order-1042",
    },
    json={"from": "Acme <hello@acme.com>", "to": ["user@example.com"], "subject": "Receipt", "html": "<p>Thanks</p>"},
)

Regeln

Unterstützt bei POST /emails und POST /emails/batch.
Der Schlüssel ist 1 bis 256 Zeichen lang.
Schlüssel gelten pro Team und werden 24 Stunden lang gespeichert.
Gleicher Schlüssel und gleicher Request-Body: Die gespeicherte Antwort wird zurückgegeben (gleicher Status, gleicher Body), es wird nichts Neues gesendet.
Gleicher Schlüssel und ein anderer Body: 409 invalid_idempotent_request.
Gleicher Schlüssel, während die erste Anfrage noch läuft: 409 concurrent_idempotent_requests. Warte einen Moment und wiederhole die Anfrage.
Ein Schlüssel mit weniger als 1 oder mehr als 256 Zeichen: 400 invalid_idempotency_key.
Fehlgeschlagene Anfragen werden nicht gespeichert, du kannst also das Problem beheben und den Schlüssel erneut verwenden.

“Gleicher Body” bedeutet, dass das geparste JSON identisch ist. Jede Änderung eines Felds, auch bei scheduled_at: "in 1 hour" (das zum Zeitpunkt der Anfrage ausgewertet wird), zählt als andere Anfrage.

Schlüssel wählen

Leite den Schlüssel aus dem fachlichen Ereignis ab, nicht aus einem Zufallswert, der erst beim Wiederholen erzeugt wird:

Gut	Schlecht
`receipt-order-1042`	`crypto.randomUUID()` bei jedem Versuch
`welcome-user-u_1042`	`Date.now()`
`digest-2026-w43-chunk-3`	Dieselbe Konstante für jede E-Mail