Sign inGet Started

Idempotentie

Netwerken falen op de slechtst mogelijke momenten: je POST een verzending, de verbinding valt weg en je weet niet of de e-mail is verstuurd. Idempotentie laat je dat verzoek veilig opnieuw proberen. Stuur dezelfde Idempotency-Key-header nogmaals mee en Bird speelt het oorspronkelijke antwoord opnieuw af in plaats van het verzoek een tweede keer te verwerken.

Hoe het werkt

Idempotency 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 met werkruimte- en organisatiescope de hieronder beschreven response-replay. Mutaties die alleen voor gebruikers gelden, ongeauthenticeerde mutaties zonder scope en streams slaan dit over. Operaties met een apart replay-contract beschrijven hun gedrag op hun referentiepagina. Bijvoorbeeld: Een spraakoproep aanmaken bewaart de oorspronkelijke acceptatie-snapshot voor overeenkomende retries wanneer je een key meegeeft.
De SDK's genereren een key voor elke muterende aanroep en hergebruiken deze bij automatische retries, inclusief het aanmaken van oproepen. Je hoeft er geen op te geven voor automatische SDK-retries. Geef je eigen key op wanneer één beoogde operatie meerdere SDK-aanroepen omvat, zoals een retry na het herstarten van je applicatie. 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" },
);
Een key is een willekeurige niet-lege string van maximaal 255 tekens. Een lege headerwaarde slaat deduplicatie over. Het aanbevolen formaat is een deterministische key afgeleid van je eigen entiteiten, <event-type>/<entity-id> (bijvoorbeeld welcome-user/usr_abc123), zodat retries na herstarts van het proces dezelfde key delen; een willekeurige UUID per logische operatie werkt ook. De Bird SDK's genereren automatisch een UUID-key voor elk muterend verzoek en hergebruiken deze bij hun interne retries.
Sleutels zijn beperkt tot je werkruimte, of tot je organisatie bij organisatie-niveau-endpoints. Een voltooid antwoord wordt 3 uur bewaard; een herhaalpogina na dat venster wordt als een nieuw verzoek verwerkt. Het venster dekt gangbare retry-schema's. Na het verlopen blijft er geen deduplicatierecord over.

Replays

Wanneer Bird een sleutel ziet die al is voltooid, geeft het het gecachte antwoord terug, dezelfde statuscode, dezelfde body, zonder het verzoek opnieuw uit te voeren. Afgespeelde antwoorden bevatten één extra header zodat je ze kunt onderscheiden van verse verwerking:
Codevoorbeeld
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 bewaard is, speelt een ongewijzigde nieuwe poging die opnieuw af, en een gewijzigd verzoek geeft 409 E01005 IdempotencyKeyReuse terug. 5xx-antwoorden worden niet bewaard, dus probeer ze opnieuw met dezelfde sleutel en hetzelfde verzoek.

Foutscenario's

ScenarioAntwoord
Dezelfde sleutel, hetzelfde verzoek, origineel voltooidGecacht antwoord afgespeeld met Idempotency-Replay: true
Dezelfde sleutel, andere request-body of endpoint409, E01005 IdempotencyKeyReuse
Dezelfde sleutel, oorspronkelijk verzoek nog onderweg409, E01004 RequestInProgress
Sleutel langer dan 255 tekens op een endpoint dat de header declareert422, E01001 ValidationError
Idempotentiebeveiliging niet beschikbaar vóór uitvoering503, E01033 IdempotencyUnavailable; deze poging wordt niet uitgevoerd
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, doorgaans een agressieve client-side timeout die opnieuw probeert terwijl de eerste poging nog wordt verwerkt. De in-flight-vergrendeling verloopt binnen 30 seconden; wacht even en probeer opnieuw. Zie Fouten voor het foutantwoord waar deze in verpakt zijn.

Wat niet gecacht wordt

5xx-antwoorden worden nooit gecacht. De sleutel wordt ontgrendeld en Bird kan een herhaalpogina als nieuwe poging verwerken. Probeer 5xx-antwoorden en time-outs opnieuw met backoff, met dezelfde sleutel en hetzelfde verzoek. Een operatie kan effect hebben voordat het antwoord wordt vastgelegd; als dat antwoord verloren gaat of de in-flight-vergrendeling verloopt, kan een herhaalpogina de operatie opnieuw uitvoeren.
Als idempotentiebescherming niet beschikbaar is vóór uitvoering, retourneert de API 503 E01033 IdempotencyUnavailable zonder deze poging uit te voeren. Behoud de sleutel bij elke herhaalpogina. 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 opnieuw bij netwerkfouten, time-outs en 5xx met exponentiële backoff, elke keer met dezelfde sleutel.
  • Behandel 409 IdempotencyKeyReuse als een fout in je sleutelgeneratie. Probeer het niet opnieuw.
  • Keys zijn optioneel bij mutaties. Gebruik er een wanneer je retry-bescherming nodig hebt; laat de key weg bij GET-verzoeken.

Volgende stappen

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.