Idempotentie

Gebruik Idempotency-Key wanneer je door een mislukte verbinding niet weet of je verzoek is geslaagd. De garantie is acceptatie van precies één keer: nieuwe pogingen met dezelfde sleutel en een identiek verzoek moeten binnen het bewaarvenster van 3 uur tot één geaccepteerde operatie leiden, ook als je het oorspronkelijke antwoord kwijt bent.

Hoe het werkt

Idempotentie is opt-in. Voeg een Idempotency-Key-header toe aan een ondersteund POST-, PATCH-, PUT- of DELETE-verzoek. Verzoeken zonder deze header worden normaal verwerkt, zonder deduplicatie. GET-verzoeken negeren de header.

Op de API voor klanten ondersteunen mutaties binnen een werkruimte of organisatie het hieronder beschreven opnieuw afspelen van antwoorden. Operaties die alleen aan een gebruiker gebonden zijn, ongeauthenticeerde operaties zonder bereik en streams slaan dit over. Operaties met een apart replay-contract beschrijven hun gedrag op hun referentiepagina. Zo bewaart Een spraakoproep aanmaken de oorspronkelijke acceptatie-snapshot voor overeenkomende nieuwe pogingen wanneer je een sleutel meegeeft.

De SDK's genereren een sleutel voor elke muterende aanroep en hergebruiken die bij automatische nieuwe pogingen, ook bij het aanmaken van oproepen. Voor automatische nieuwe pogingen via SDK hoef je zelf geen sleutel op te geven. Geef wel je eigen sleutel op wanneer één beoogde operatie meerdere afzonderlijke SDK-aanroepen omvat, zoals een nieuwe poging nadat je je applicatie opnieuw hebt gestart. Deze voorbeelden tonen dat geval.

await bird.email.send(
  {
    from: "hello@yourdomain.com",
    to: ["delivered@messagebird.dev"],
    subject: "Welcome!",
    html: "<p>Thanks for signing up.</p>",
  },
  { idempotencyKey: "welcome-user/usr_abc123" },
);

client.email.send(
    from_="hello@yourdomain.com",
    to=["delivered@messagebird.dev"],
    subject="Welcome!",
    html="<p>Thanks for signing up.</p>",
    options={"idempotency_key": "welcome-user/usr_abc123"},
)

_, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:    "hello@yourdomain.com",
	To:      []string{"delivered@messagebird.dev"},
	Subject: "Welcome!",
	HTML:    "<p>Thanks for signing up.</p>",
}, option.WithIdempotencyKey("welcome-user/usr_abc123"))

$bird->email->send(
    from: 'hello@yourdomain.com',
    to: ['delivered@messagebird.dev'],
    subject: 'Welcome!',
    html: '<p>Thanks for signing up.</p>',
    options: new RequestOptions(idempotencyKey: 'welcome-user/usr_abc123'),
);

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-user/usr_abc123" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Welcome!",
    "html": "<p>Thanks for signing up.</p>"
  }'

Een sleutel is een niet-lege string van maximaal 255 tekens. Bij een lege headerwaarde wordt deduplicatie overgeslagen. Het aanbevolen formaat is een deterministische sleutel die je afleidt van je eigen entiteiten, <event-type>/<entity-id> (bijvoorbeeld welcome-user/usr_abc123), zodat nieuwe pogingen na een herstart van het proces dezelfde sleutel delen; een willekeurige UUID per logische operatie werkt ook. De Bird SDK's genereren automatisch een UUID-sleutel voor elk muterend verzoek en hergebruiken die bij hun interne nieuwe pogingen.

Sleutels gelden voor je werkruimte, of voor je organisatie bij endpoints op organisatieniveau. Een voltooid antwoord wordt 3 uur bewaard; een nieuwe poging na dat venster kan als nieuw verzoek worden verwerkt. Als de uitkomst van de oorspronkelijke operatie na het verlopen onbekend is, laat je die operatie onopgelost en stem je haar af voordat je opnieuw verstuurt.

Replays

Een overeenkomende nieuwe poging binnen drie uur moet tot de oorspronkelijke operatie leiden. Als het antwoord daarvan is bewaard, geeft de API dezelfde statuscode en body terug zonder nog een operatie te accepteren. Opnieuw afgespeelde antwoorden bevatten één extra header, zodat je ze kunt onderscheiden van een nieuwe verwerking:

HTTP/1.1 202 Accepted
Idempotency-Replay: true

Bewaarde antwoorden kunnen 4xx-afwijzingen bevatten. Gebruik een nieuwe sleutel wanneer je een verzoek corrigeert: als de afwijzing is bewaard, speelt een ongewijzigde nieuwe poging die opnieuw af, en een gewijzigd verzoek geeft 409 E01005 IdempotencyKeyReuse terug. 5xx-antwoorden worden niet als voltooide antwoorden bewaard. De garantie van acceptatie van precies één keer geldt ook voor nieuwe pogingen na deze fouten.

Foutscenario's

Het hergebruiken van een voltooide sleutel met een ander verzoek wordt behandeld als een clientfout: Bird geeft onmiddellijk 409 terug in plaats van je stilzwijgend een antwoord te geven dat niet overeenkomt met wat je verstuurde. Genereer een nieuwe sleutel voor het nieuwe verzoek. De vergelijking omvat de methode, het endpoint, pad- en queryparameters, en de onbewerkte request-body, inclusief JSON-witruimte. Multipart-uploads vergelijken partnamen, bestandsnamen en inhoud; boundaries en de volgorde van parts hebben geen invloed op replay.

RequestInProgress betekent dat een gelijktijdig verzoek met dezelfde sleutel nog niet is afgerond. Meestal komt dat door een agressieve client-side time-out die opnieuw probeert terwijl de eerste poging nog wordt verwerkt. Wacht even en probeer het opnieuw met dezelfde sleutel en hetzelfde verzoek. Zie Fouten voor het foutantwoord waarin deze fouten worden teruggegeven.

Wat niet gecacht wordt

5xx-antwoorden worden niet bewaard als voltooide antwoorden. Probeer het binnen drie uur opnieuw met begrensde backoff, dezelfde sleutel en een identiek verzoek. De garantie op eenmalige acceptatie geldt ook als het oorspronkelijke antwoord verloren is gegaan.

Als idempotentiebescherming niet beschikbaar is vóór uitvoering, retourneert de API 503 E01033 IdempotencyUnavailable zonder deze poging uit te voeren. Behoud de sleutel telkens wanneer je het opnieuw probeert. Deze fout beschrijft niet de uitkomst van een eerdere poging met dezelfde sleutel.

Praktische richtlijnen

• Genereer één sleutel per logische operatie en hergebruik die voor elke HTTP-poging van die operatie.
• Probeer het bij netwerkfouten, time-outs en 5xx binnen drie uur opnieuw met begrensde exponentiële backoff, met dezelfde sleutel en een identiek verzoek.
• Laat een onbekende uitkomst onopgelost wanneer je geen nieuwe pogingen meer hebt of de bewaartermijn is verlopen. Stem de status af voordat je een nieuwe operatie indient, met de oude sleutel of met een nieuwe.
• Controleer bij het verzenden van berichten na acceptatie de berichtstatus om de aflevering te bevestigen.
• Behandel 409 IdempotencyKeyReuse als een fout in je sleutelgeneratie. Probeer het niet opnieuw.
• Sleutels zijn optioneel bij mutaties. Gebruik er een wanneer je bescherming nodig hebt bij een nieuwe poging; laat de sleutel weg bij GET-verzoeken.

Volgende stappen

• Idempotentie API-referentie: header- en response-headerschema's
• SDK-concepten: automatische sleutelgeneratie en het gedrag bij een nieuwe poging in de SDK's
• Fouten: het foutantwoord en de codecatalogus
• E-mail verzenden: send- en batch-endpoints