Idempotency-Key-header

De Bird-API ondersteunt optionele deduplicatie van verzoeken via de header Idempotency-Key. Deze pagina beschrijft het HTTP-contract; zie Idempotentie voor de strategie bij opnieuw proberen.

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.

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 een ongewijzigde herhaling die opnieuw terug en geeft een gewijzigd verzoek 409 E01005 IdempotencyKeyReuse terug.

5xx-responses worden nooit gecacht. Probeer opnieuw met backoff met dezelfde sleutel en hetzelfde verzoek. E01033 IdempotencyUnavailable betekent dat deze poging niet is uitgevoerd; het beschrijft niet de uitkomst van een eerdere poging. Behoud de sleutel bij elke nieuwe poging.

Een operatie kan effect hebben voordat de response is opgeslagen. Als die response verloren gaat, of de in-flight-vergrendeling verloopt, kan een retry de operatie opnieuw uitvoeren. Een timeout of een andere 5xx-response bewijst daarom niet dat de operatie geen effect had.

De officiële SDK's voegen een automatisch gegenereerde UUID Idempotency-Key toe aan elk muterend verzoek, eenmalig gegenereerd per logische aanroep en hergebruikt bij alle retrypogingen van die aanroep. Je kunt per aanroep een eigen sleutel meegeven (idempotencyKey in TypeScript, option.WithIdempotencyKey in Go, idempotency_key in Python) wanneer één logische operatie 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.