Idempotency-Key-header

Gebruik Idempotency-Key om een verzoek opnieuw te proberen zonder een dubbele bewerking aan te maken. De garantie is precies eenmalige acceptatie: binnen de bewaartermijn van 3 uur moeten nieuwe pogingen met dezelfde sleutel en een identiek verzoek leiden tot de oorspronkelijke bewerking, ook als je het antwoord daarvan kwijt bent. Zie Idempotentie voor de strategie voor nieuwe pogingen.

Requestheader

Mutaties binnen een werkruimte of organisatie ondersteunen het hieronder beschreven opnieuw teruggeven van opgeslagen antwoorden. Bewerkingen die uitsluitend aan een gebruiker zijn gekoppeld, niet-geauthenticeerde bewerkingen zonder bereik en streams gebruiken dit niet. Bewerkingen met een eigen contract voor het opnieuw teruggeven van antwoorden beschrijven hun gedrag op hun referentiepagina.

Als je de header weglaat of een lege waarde verstuurt, wordt het verzoek normaal verwerkt, zonder deduplicatie. Bij endpoints die deze header declareren, geeft een sleutel van meer dan 255 tekens 422 terug met code E01001 ValidationError.

Sleutels gelden binnen je werkruimte, of binnen je organisatie bij endpoints op organisatieniveau, en worden ongeveer 3 uur bewaard. Na die bewaartermijn wordt een verzoek dat de sleutel opnieuw gebruikt als een nieuw verzoek verwerkt.

Response-semantiek

Een herhaalde response is byte voor byte het origineel (dezelfde statuscode, dezelfde body), alleen te onderscheiden door de extra header:

HTTP/1.1 202 Accepted
Idempotency-Replay: true

"Identical request" omvat de methode, het endpoint, de pad- en queryparameters en de onbewerkte verzoekbody. Een verschil in deze waarden, inclusief witruimte in JSON, veroorzaakt E01005. Bij multipart-uploads worden onderdeelnamen, bestandsnamen en inhoud vergeleken; de scheidingstekens en volgorde van onderdelen hebben geen invloed op het opnieuw teruggeven van het antwoord. Beide 409-fouten worden verpakt in het standaard foutantwoord.

Bewaarde antwoorden kunnen 4xx-afwijzingen bevatten. Gebruik een nieuwe sleutel als je een verzoek corrigeert: als de afwijzing is bewaard, geeft opnieuw proberen met een ongewijzigd verzoek die afwijzing opnieuw terug, en geeft een gewijzigd verzoek 409 E01005 IdempotencyKeyReuse terug.

Probeer een timeout of 5xx binnen drie uur opnieuw met begrensde backoff, met dezelfde sleutel en een identiek verzoek. De garantie van precies eenmalige acceptatie geldt ook als het oorspronkelijke antwoord verloren is gegaan. E01033 IdempotencyUnavailable betekent dat deze poging niet is uitgevoerd; het zegt niets over de uitkomst van een eerdere poging. Behoud de sleutel bij elke nieuwe poging.

Bij het verzenden van een bericht betekent precies eenmalige acceptatie dat overeenkomende nieuwe pogingen samen één geaccepteerde verzending opleveren. Controleer de berichtstatus om de bezorging te bevestigen. Controleer na drie uur de uitkomst van de oorspronkelijke bewerking voordat je opnieuw verstuurt: een verlopen of nieuwe sleutel kan een extra bewerking aanmaken.

Gedrag van SDK

De officiële SDK's voegen een automatisch gegenereerde UUID Idempotency-Key toe aan elk muterend verzoek. Die wordt eenmalig per logische aanroep gegenereerd en hergebruikt bij elke nieuwe poging van die aanroep. Je kunt per aanroep een eigen sleutel meegeven (idempotencyKey in TypeScript, option.WithIdempotencyKey in Go, idempotency_key in Python, new RequestOptions(idempotencyKey: ...) in PHP) wanneer één logische bewerking meerdere SDK-aanroepen omvat. Om een replay te detecteren lees je de Idempotency-Replay-responseheader via de transport-metadata-accessor van elke SDK: .withResponse() in TypeScript, option.WithResponseInto in Go en with_raw_response in Python.

Gerelateerd

• Idempotentieconcepten: strategie voor opnieuw proberen, sleutelontwerp en replay-limieten
• Foutresponses: het foutantwoord rond E01004 en E01005
• E-mailberichten: het verzendendpoint, de meest gebruikelijke plek om een sleutel te gebruiken
• SDK-concepten: automatische sleutelgeneratie en nieuwe pogingen