Skip to main content
Hver autentificeret POST på Current API accepterer en Idempotency-Key-header. Når en anmodning med en nøgle lykkes, gemmes dens svar i 24 timer. Et nyt forsøg med den samme nøgle afspiller det gemte svar igen i stedet for at udføre anmodningen igen. Det gør det sikkert at prøve en anmodning igen, der fik timeout eller fejlede på din side, uden at risikere en dobbelt opkrævning, overførsel eller ressource. Enhver unik streng på op til 255 bytes fungerer som nøgle – et UUID er et godt standardvalg. Generér en ny nøgle for hver særskilt handling, og genbrug kun præcis den nøgle til at prøve den handling igen.
Genafspillede svar er byte for byte identiske med originalen – inklusive statuskoden – og har en Idempotent-Replayed: true-header, så du kan skelne en genafspilning fra en ny udførelse.
Fejlsvar genafspilles også. Hvis den oprindelige anmodning fejlede med en 4xx, returnerer et nyt forsøg med den samme nøgle den samme fejl. Den fejl var anmodningens reelle resultat – send i stedet en ny nøgle med den rettede anmodning.
Et par detaljer, der er værd at kende:
  • “Samme anmodning” betyder, at metode, sti, forespørgselsstreng, body og Api-Version-Date alle matcher originalen præcist. Enhver forskel behandles som genbrug af nøglen og afvises med en 400, hvis error.code er idempotency_key_mismatch.
  • Nøgler er afgrænset til den autentificerede kalder. To forskellige API-nøgler eller brugere kan bruge den samme nøgleværdi uden at kollidere.
  • Headeren ignoreres på uautentificerede anmodninger og på metoder, der ikke er POST – GET-, PATCH- og DELETE-anmodninger er sikre at prøve igen.
  • Mens den første anmodning med en nøgle stadig kører, returnerer et nyt forsøg en 409, hvis error.code er idempotency_request_in_progress. Hvis den første anmodning fejlede med et ukendt resultat (for eksempel et servernedbrud midt i anmodningen), bliver nye forsøg ved med at returnere den 409, indtil nøglen udløber. API’et risikerer aldrig at udføre en anmodning to gange.