Idempotente forespørsler

En forespørsel kan mislykkes etter at Sursa allerede har gjort jobben: Tilkoblingen brytes, eller prosessen din starter på nytt før svaret kommer. Hvis du sender den samme POST en gang til, kan du opprette et ekstra kort eller en ekstra webhook. En idempotensnøkkel hindrer det.

Send en Idempotency-Key-header med hver POST og PATCH. Hvis Sursa allerede har sett en forespørsel med denne nøkkelen, kjører den ikke operasjonen på nytt: Den returnerer svaret den lagret første gang.

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

En gjentatt forespørsel får samme status og brødtekst som den første, med en ekstra header:

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

Den gjentatte forespørselen har sin egen X-Request-Id.

Velge en nøkkel

Bruk en ny tilfeldig verdi, for eksempel en UUID v4, for hver logiske operasjon: «opprett dette kortet», «registrer denne webhooken». Bruk den samme verdien for hvert nytt forsøk på den operasjonen, og aldri for en annen.
En god nøkkel avledes fra dine egne data når du har slike, for eksempel sync-2026-10-24-record-1042. Da sender selv en jobb som er startet på nytt og har mistet minnet sitt, den samme nøkkelen igjen.
Nøkkelen består av 1 til 255 utskrivbare ASCII-tegn. Alt annet returnerer 400 med koden api.idempotency_key_invalid.

Hva Sursa gjør med nøkkelen

Situasjon	Svar
Første forespørsel med denne nøkkelen	Operasjonen kjører som vanlig.
Samme nøkkel, samme forespørsel, den første endte med `2xx` eller `4xx`	Det lagrede svaret, med `Idempotency-Replayed: true`. Operasjonen kjører ikke på nytt.
Samme nøkkel, den første forespørselen kjører fortsatt	`409` `api.idempotency_in_progress` med `Retry-After: 1`. Vent, og prøv på nytt.
Samme nøkkel, en annen metode, bane, `Content-Type` eller brødtekst	`409` `api.idempotency_mismatch`. Nøkkelen er allerede tatt av en annen forespørsel.
Den første forespørselen endte med `5xx` eller `429`	Nøkkelen frigis: Den neste forespørselen med den kjører operasjonen på nytt.

En nøkkel er gyldig i 24 timer. Etter det starter den samme nøkkelen en ny operasjon.
Nøklene er atskilt per organisasjon og per avsender: To forskjellige API-nøkler kan bruke den samme verdien uten å påvirke hverandre.
Et feilsvar med 4xx lagres også. En forespørsel som ikke besto valideringen, mislykkes på samme måte når den gjentas med samme nøkkel; rett den, og send den med en ny nøkkel.

Hvilke forespørsler som trenger den

Metode	Idempotency-Key
`POST`, `PATCH`	Send den. Hver operasjon som lagrer svaret sitt for en gjentakelse, oppgir headeren i API-referansen.
`GET`, `PUT`, `DELETE`	Ikke nødvendig: Disse metodene er i sin natur trygge å gjenta. Headeren godtas og har ingen virkning.
`POST` som bare leser, for eksempel søk, de økonomiske rapportene og `POST /v1/catalog/resolve`	Godtas, men ingenting lagres: Forespørselen kjører ganske enkelt på nytt.

Noen operasjoner er trygge å gjenta selv uten headeren:

PUT /v1/cards-by-external-id/{external_id} oppretter eller erstatter kortet med ID-en din; en gjentakelse med samme innhold endrer ingenting.
Dokumenter i en egendefinert kilde identifiseres med din external_id; sender du det samme dokumentet på nytt, returneres unchanged.
Et strømmet svar fra POST /v1/chat bruker feltet request_id i brødteksten i stedet for headeren. Se Bygg en bot for spørsmål og svar.

Trygge nye forsøk

Kombiner nøkkelen med reglene for nye forsøk i Feil: Opprett nøkkelen én gang, før det første forsøket, og send den med hvert forsøk på den samme operasjonen.