Idempotentni zahtjevi

Zahtjev može ne uspjeti nakon što je Sursa već obavila posao: veza se prekine ili se vaš proces ponovno pokrene prije nego što stigne odgovor. Ako ponovno pošaljete isti POST, mogli biste stvoriti drugu karticu ili drugi webhook. Ključ idempotentnosti to sprječava.

Uz svaki POST i PATCH pošaljite zaglavlje Idempotency-Key. Ako je Sursa već vidjela zahtjev s tim ključem, ne izvršava operaciju ponovno: vraća odgovor koji je spremila prvi put.

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

Ponovljeni zahtjev dobiva isti status i tijelo kao i prvi, uz dodatno zaglavlje:

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

Ponovljeni zahtjev ima vlastiti X-Request-Id.

Odabir ključa

Za svaku logičku operaciju koristite novu nasumičnu vrijednost, kao što je UUID v4: „stvori ovu karticu”, „registriraj ovaj webhook”. Istu vrijednost koristite za svaki ponovni pokušaj te operacije, a nikada za neku drugu.
Dobar se ključ izvodi iz vaših vlastitih podataka kad ih imate, na primjer sync-2026-10-24-record-1042. Tada čak i ponovno pokrenut posao koji je izgubio svoje stanje ponovno šalje isti ključ.
Ključ ima od 1 do 255 ispisivih ASCII znakova. Sve ostalo vraća 400 s kodom api.idempotency_key_invalid.

Što Sursa radi s ključem

Situacija	Odgovor
Prvi zahtjev s ovim ključem	Operacija se izvršava kao i obično.
Isti ključ, isti zahtjev, prvi je završio s `2xx` ili `4xx`	Spremljeni odgovor, uz `Idempotency-Replayed: true`. Operacija se ne izvršava ponovno.
Isti ključ, prvi se zahtjev još izvršava	`409` `api.idempotency_in_progress` uz `Retry-After: 1`. Pričekajte i pokušajte ponovno.
Isti ključ, druga metoda, putanja, `Content-Type` ili tijelo	`409` `api.idempotency_mismatch`. Ključ je već zauzet drugim zahtjevom.
Prvi je zahtjev završio s `5xx` ili `429`	Ključ se oslobađa: sljedeći zahtjev s njim ponovno izvršava operaciju.

Ključ vrijedi 24 sata. Nakon toga isti ključ pokreće novu operaciju.
Ključevi su odvojeni po organizaciji i po pozivatelju: dva različita API ključa mogu koristiti istu vrijednost, a da ne utječu jedan na drugi.
Sprema se i odgovor s pogreškom 4xx. Zahtjev koji nije prošao provjeru valjanosti ne uspijeva na isti način kad se ponovi s istim ključem; ispravite ga i pošaljite s novim ključem.

Kojim je zahtjevima potreban

Metoda	Idempotency-Key
`POST`, `PATCH`	Pošaljite ga. Svaka operacija koja sprema svoj odgovor za ponavljanje navodi to zaglavlje u referenci API-ja.
`GET`, `PUT`, `DELETE`	Nije potreban: te je metode po njihovu značenju sigurno ponavljati. Zaglavlje se prihvaća i nema učinka.
`POST` koji samo čita, kao što su pretraživanje, financijska izvješća i `POST /v1/catalog/resolve`	Prihvaća se, ali ništa se ne sprema: zahtjev se jednostavno ponovno izvršava.

Neke je operacije sigurno ponavljati i bez zaglavlja:

PUT /v1/cards-by-external-id/{external_id} stvara ili zamjenjuje karticu s vašim ID-om; ponavljanje s istim sadržajem ne mijenja ništa.
Dokumenti vlastitog izvora prepoznaju se prema vašem external_id; ponovno slanje istog dokumenta vraća unchanged.
Odgovor koji POST /v1/chat šalje kao tok umjesto zaglavlja koristi polje request_id u tijelu. V. Izrada bota za pitanja i odgovore.

Sigurni ponovni pokušaji

Kombinirajte ključ s pravilima ponovnih pokušaja iz vodiča Pogreške: stvorite ključ jednom, prije prvog pokušaja, i šaljite ga pri svakom pokušaju iste operacije.