Idempotens

Nettverk feiler. Et POST-kall kan nå oss, bli utført, og svaret kan gå tapt på vei tilbake. Uten idempotens vil et gjenforsøk opprette objektet på nytt: to fakturaer til kunden, to SMS-er med samme engangskode. Med idempotens er gjenforsøket trygt.

Slik virker det

Send hodet Idempotency-Key med en unik verdi på POST-kall:

POST /v1/fakturaer
Idempotency-Key: ordre-10422

Første gang utfører vi kallet og lagrer svaret under nøkkelen. Alle senere kall med samme nøkkel og samme kropp får det lagrede svaret tilbake, med samme statuskode, uten at noe utføres på nytt. Svaret får hodet Idempotent-Replayed: true.

Nøkler lagres i 24 timer. Deretter behandles samme nøkkel som ny.

Velg en god nøkkel

Nøkkelen bør være knyttet til handlingen i ditt system, ikke til kallet:

Nøkkelen kan være opptil 255 tegn. Den er privat for kontoen og miljøet; to kunder kan bruke ordre-1 uten å påvirke hverandre.

Samme nøkkel, annen kropp

Sender du samme nøkkel med en annen kropp, svarer vi 409 konflikt. Det er med vilje: det betyr at koden din prøver å gjenbruke en nøkkel for noe annet, og det vil du vite om.

{ "feil": { "kode": "konflikt", "melding": "Idempotency-Key «ordre-10422» er allerede brukt med en annen forespørsel." } }

Pågående kall

Kommer et kall med samme nøkkel mens det første fortsatt behandles, venter det andre på svaret fra det første (opptil 30 sekunder) og får samme resultat. Du trenger ikke låse på din side.

SDK-ene

SDK-ene setter en tilfeldig nøkkel på alle POST-kall hvis du ikke oppgir en, og bruker samme nøkkel for alle automatiske gjenforsøk av det kallet. Det beskytter mot nettverksfeil. For å beskytte mot at din kode kjører samme handling to ganger (for eksempel fordi en jobb ble startet på nytt), må du sette nøkkelen selv:

await spire.fakturaer.opprett(params, { idempotencyKey: `ordre-${ordre.id}` });

Hva som er idempotent uten nøkkel

• Alle GET-kall, per definisjon.
• DELETE: å avbryte en allerede avbrutt signering gir 200, ikke feil.
• POST /v1/fakturaer/{id}/send: å sende en allerede sendt faktura gir 409 konflikt, ikke dobbel sending. Vi anbefaler likevel nøkkel, så gjenforsøket får samme svar som originalen.

Webhooks

Webhooks kan leveres mer enn én gang. Hver hendelse har en unik id. Lagre ID-ene du har behandlet, og hopp over duplikater. Les mer under webhooks.