Idempotente requests

Een request kan mislukken nadat Sursa het werk al heeft gedaan: de verbinding valt weg, of je proces herstart voordat de response binnen is. Stuur je dezelfde POST opnieuw, dan maak je misschien een tweede kaart of een tweede webhook. Een idempotentiesleutel voorkomt dat.

Stuur bij elke POST en PATCH een header Idempotency-Key mee. Heeft Sursa al een request met deze sleutel gezien, dan voert het de bewerking niet opnieuw uit: het geeft de response terug die het de eerste keer heeft opgeslagen.

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

Een herhaald request krijgt dezelfde status en body als het eerste, met een extra header:

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

Het herhaalde request heeft een eigen X-Request-Id.

Een sleutel kiezen

Gebruik een nieuwe willekeurige waarde, zoals een UUID v4, voor elke logische bewerking: “maak deze kaart”, “registreer deze webhook”. Gebruik dezelfde waarde voor elke nieuwe poging van die bewerking, en nooit voor een andere.
Een goede sleutel leid je af van je eigen gegevens als je die hebt, bijvoorbeeld sync-2026-10-24-record-1042. Dan stuurt zelfs een herstarte job die zijn geheugen kwijt is, dezelfde sleutel opnieuw.
De sleutel bestaat uit 1 tot 255 afdrukbare ASCII-tekens. Al het andere geeft 400 met de code api.idempotency_key_invalid.

Wat Sursa met de sleutel doet

Situatie	Response
Eerste request met deze sleutel	De bewerking wordt zoals gewoonlijk uitgevoerd.
Dezelfde sleutel, hetzelfde request, het eerste eindigde met `2xx` of `4xx`	De opgeslagen response, met `Idempotency-Replayed: true`. De bewerking wordt niet opnieuw uitgevoerd.
Dezelfde sleutel, het eerste request loopt nog	`409` `api.idempotency_in_progress` met `Retry-After: 1`. Wacht en probeer het opnieuw.
Dezelfde sleutel, een andere methode, een ander pad, een andere `Content-Type` of body	`409` `api.idempotency_mismatch`. De sleutel is al in gebruik door een ander request.
Het eerste request eindigde met `5xx` of `429`	De sleutel wordt vrijgegeven: het volgende request ermee voert de bewerking opnieuw uit.

Een sleutel is 24 uur geldig. Daarna start dezelfde sleutel een nieuwe bewerking.
Sleutels zijn gescheiden per organisatie en per aanroeper: twee verschillende API-sleutels kunnen dezelfde waarde gebruiken zonder elkaar te beïnvloeden.
Een foutresponse met 4xx wordt ook opgeslagen. Een request dat niet door de validatie kwam, mislukt op dezelfde manier als het met dezelfde sleutel wordt herhaald; corrigeer het en stuur het met een nieuwe sleutel.

Welke requests een sleutel nodig hebben

Methode	Idempotency-Key
`POST`, `PATCH`	Meesturen. Elk endpoint dat zijn response voor een herhaling bewaart, vermeldt de header in de API-referentie.
`GET`, `PUT`, `DELETE`	Niet nodig: deze methoden zijn naar hun aard veilig te herhalen. De header wordt geaccepteerd en heeft geen effect.
`POST` die alleen leest, zoals zoeken, de financiële rapporten en `POST /v1/catalog/resolve`	Geaccepteerd, maar er wordt niets opgeslagen: het request wordt gewoon opnieuw uitgevoerd.

Sommige bewerkingen kun je ook zonder de header veilig herhalen:

PUT /v1/cards-by-external-id/{external_id} maakt of vervangt de kaart met jouw ID; een herhaling met dezelfde inhoud verandert niets.
Documenten van een eigen bron worden geïdentificeerd door je external_id; hetzelfde document opnieuw sturen geeft unchanged terug.
Een gestreamd antwoord van POST /v1/chat gebruikt het veld request_id van de body in plaats van de header. Zie Een vraag-en-antwoordbot bouwen.

Veilig opnieuw proberen

Combineer de sleutel met de regels voor nieuwe pogingen uit Fouten: maak de sleutel één keer, vóór de eerste poging, en stuur hem mee bij elke poging van dezelfde bewerking.