Idempotenta anrop

Ett anrop kan misslyckas efter att Sursa redan har gjort arbetet: anslutningen bryts, eller din process startar om innan svaret kommer. Om du skickar samma POST igen kan du skapa ett andra kort eller en andra webhook. En idempotensnyckel förhindrar det.

Skicka huvudet Idempotency-Key med varje POST och PATCH. Om Sursa redan har sett ett anrop med den här nyckeln körs åtgärden inte igen: Sursa returnerar svaret som sparades första gången.

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."}'

Ett upprepat anrop får samma status och brödtext som det första, med ett extra huvud:

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

Det upprepade anropet har ett eget X-Request-Id.

Välja en nyckel

Använd ett nytt slumpmässigt värde, till exempel ett UUID v4, för varje logisk åtgärd: ”skapa det här kortet”, ”registrera den här webhooken”. Använd samma värde för varje nytt försök med den åtgärden och aldrig för en annan.
En bra nyckel härleds från dina egna data när du har sådana, till exempel sync-2026-10-24-record-1042. Då skickar även ett omstartat jobb som har tappat sitt minne samma nyckel igen.
Nyckeln består av 1–255 skrivbara ASCII-tecken. Allt annat returnerar 400 med koden api.idempotency_key_invalid.

Vad Sursa gör med nyckeln

Situation	Svar
Första anropet med den här nyckeln	Åtgärden körs som vanligt.
Samma nyckel, samma anrop, det första avslutades med `2xx` eller `4xx`	Det sparade svaret, med `Idempotency-Replayed: true`. Åtgärden körs inte igen.
Samma nyckel, det första anropet körs fortfarande	`409` `api.idempotency_in_progress` med `Retry-After: 1`. Vänta och försök igen.
Samma nyckel, en annan metod, sökväg, `Content-Type` eller brödtext	`409` `api.idempotency_mismatch`. Nyckeln används redan av ett annat anrop.
Det första anropet avslutades med `5xx` eller `429`	Nyckeln frigörs: nästa anrop med den kör åtgärden igen.

En nyckel gäller i 24 timmar. Därefter startar samma nyckel en ny åtgärd.
Nycklarna är separata per organisation och per anropare: två olika API-nycklar kan använda samma värde utan att påverka varandra.
Ett felsvar med 4xx sparas också. Ett anrop som inte klarade valideringen misslyckas på samma sätt när det upprepas med samma nyckel; rätta det och skicka det med en ny nyckel.

Vilka anrop som behöver den

Metod	Idempotency-Key
`POST`, `PATCH`	Skicka den. Varje slutpunkt som sparar sitt svar för en upprepning anger huvudet i API-referensen.
`GET`, `PUT`, `DELETE`	Behövs inte: de här metoderna är till sin natur säkra att upprepa. Huvudet godtas och har ingen effekt.
`POST` som bara läser, till exempel sökning, de finansiella rapporterna och `POST /v1/catalog/resolve`	Godtas, men inget sparas: anropet körs helt enkelt igen.

Vissa åtgärder är säkra att upprepa även utan huvudet:

PUT /v1/cards-by-external-id/{external_id} skapar eller ersätter kortet med ditt id; en upprepning med samma innehåll ändrar ingenting.
Dokument i en egen källa identifieras med ditt external_id; skickar du samma dokument igen returneras unchanged.
Ett strömmat svar från POST /v1/chat använder fältet request_id i brödtexten i stället för huvudet. Se Bygg en fråga-svar-bot.

Försök igen på ett säkert sätt

Kombinera nyckeln med reglerna för nya försök i Fel: skapa nyckeln en gång, före det första försöket, och skicka den med varje försök med samma åtgärd.