Idempotente anmodninger

En anmodning kan mislykkes, efter at Sursa allerede har udført arbejdet: Forbindelsen afbrydes, eller din proces genstarter, før svaret når frem. Sender du den samme POST igen, kan du komme til at oprette et kort eller en webhook mere. En idempotensnøgle forhindrer det.

Send en Idempotency-Key-header med hver POST og PATCH. Har Sursa allerede set en anmodning med denne nøgle, udfører den ikke operationen igen: Den returnerer det svar, den gemte 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 gentaget anmodning 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 gentagne anmodning har sit eget X-Request-Id.

Valg af nøgle

Brug en ny tilfældig værdi, fx et UUID v4, for hver logisk operation: »opret dette kort«, »registrér denne webhook«. Brug den samme værdi ved hvert nyt forsøg på den operation og aldrig til en anden.
En god nøgle afledes af dine egne data, når du har dem, fx sync-2026-10-24-record-1042. Så sender selv et genstartet job, der har mistet sin hukommelse, den samme nøgle igen.
Nøglen består af 1 til 255 printbare ASCII-tegn. Alt andet returnerer 400 med koden api.idempotency_key_invalid.

Hvad Sursa gør med nøglen

Situation	Svar
Første anmodning med denne nøgle	Operationen udføres som normalt.
Samme nøgle, samme anmodning, den første sluttede med `2xx` eller `4xx`	Det gemte svar med `Idempotency-Replayed: true`. Operationen udføres ikke igen.
Samme nøgle, den første anmodning kører stadig	`409` `api.idempotency_in_progress` med `Retry-After: 1`. Vent, og forsøg igen.
Samme nøgle, en anden metode, sti, `Content-Type` eller brødtekst	`409` `api.idempotency_mismatch`. Nøglen er allerede optaget af en anden anmodning.
Den første anmodning sluttede med `5xx` eller `429`	Nøglen frigives: Den næste anmodning med den udfører operationen igen.

En nøgle gælder i 24 timer. Derefter starter den samme nøgle en ny operation.
Nøgler er adskilte pr. organisation og pr. kalder: To forskellige API-nøgler kan bruge den samme værdi uden at påvirke hinanden.
Et fejlsvar med 4xx gemmes også. En anmodning, der ikke bestod valideringen, mislykkes på samme måde, når den gentages med samme nøgle; ret den, og send den med en ny nøgle.

Hvilke anmodninger der skal have den

Metode	Idempotency-Key
`POST`, `PATCH`	Send den. Alle operationer, der gemmer deres svar til en gentagelse, viser headeren i API-referencen.
`GET`, `PUT`, `DELETE`	Ikke nødvendig: Disse metoder kan efter deres betydning trygt gentages. Headeren accepteres og har ingen virkning.
`POST`, der kun læser, fx søgning, de økonomiske rapporter og `POST /v1/catalog/resolve`	Accepteres, men intet gemmes: Anmodningen udføres blot igen.

Nogle operationer kan trygt gentages selv uden headeren:

PUT /v1/cards-by-external-id/{external_id} opretter eller erstatter kortet med dit id; en gentagelse med samme indhold ændrer ingenting.
Dokumenter i en brugerdefineret kilde identificeres ved dit external_id; sender du det samme dokument igen, returneres unchanged.
Et streamet svar fra POST /v1/chat bruger feltet request_id i brødteksten i stedet for headeren. Se Byg en Q&A-bot.

Sikre nye forsøg

Kombinér nøglen med reglerne for nye forsøg fra Fejl: Opret nøglen én gang, før det første forsøg, og send den med hvert forsøg på den samme operation.