Idempotentiškos užklausos

Užklausa gali nepavykti, kai Sursa darbą jau atliko: nutrūksta ryšys arba jūsų procesas paleidžiamas iš naujo, kol dar negautas atsakas. Jei vėl išsiųsite tą pačią POST užklausą, galite sukurti antrą kortelę ar antrą webhook galinį tašką. To išvengti padeda idempotentiškumo raktas.

Su kiekviena POST ir PATCH užklausa siųskite antraštę Idempotency-Key. Jei Sursa jau gavo užklausą su šiuo raktu, ji operacijos nevykdo iš naujo, o grąžina pirmą kartą išsaugotą atsaką.

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

Pakartota užklausa gauna tą pačią būseną ir turinį kaip pirmoji, su papildoma antrašte:

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

Pakartota užklausa turi savo X-Request-Id.

Kaip pasirinkti raktą

Kiekvienai loginei operacijai – „sukurti šią kortelę“, „užregistruoti šį webhook galinį tašką“ – naudokite naują atsitiktinę reikšmę, pavyzdžiui, UUID v4. Tą pačią reikšmę naudokite kiekvienam tos operacijos pakartojimui ir niekada – kitai operacijai.
Geras raktas išvedamas iš jūsų pačių duomenų, jei tokių turite, pavyzdžiui, sync-2026-10-24-record-1042. Tada net iš naujo paleistas darbas, praradęs atmintį, vėl siunčia tą patį raktą.
Raktas – nuo 1 iki 255 spausdinamų ASCII simbolių. Kitokia reikšmė grąžina 400 su kodu api.idempotency_key_invalid.

Ką Sursa daro su raktu

Situacija	Atsakas
Pirmoji užklausa su šiuo raktu	Operacija vykdoma įprastai.
Tas pats raktas, ta pati užklausa, pirmoji baigėsi `2xx` arba `4xx`	Išsaugotas atsakas su `Idempotency-Replayed: true`. Operacija iš naujo nevykdoma.
Tas pats raktas, pirmoji užklausa dar vykdoma	`409` `api.idempotency_in_progress` su `Retry-After: 1`. Palaukite ir pakartokite.
Tas pats raktas, kitas metodas, kelias, `Content-Type` arba turinys	`409` `api.idempotency_mismatch`. Raktą jau užėmė kita užklausa.
Pirmoji užklausa baigėsi `5xx` arba `429`	Raktas atlaisvinamas: kita užklausa su juo vėl vykdo operaciją.

Raktas galioja 24 valandas. Po to tas pats raktas pradeda naują operaciją.
Raktai atskiri kiekvienai organizacijai ir kiekvienam užklausos siuntėjui: du skirtingi API raktai gali naudoti tą pačią reikšmę vienas kitam netrukdydami.
Klaidos atsakas su 4xx taip pat išsaugomas. Validavimo nepraėjusi užklausa, pakartota su tuo pačiu raktu, nepavyksta taip pat; pataisykite ją ir siųskite su nauju raktu.

Kurioms užklausoms jo reikia

Metodas	Idempotency-Key
`POST`, `PATCH`	Siųskite. Kiekviena operacija, kuri išsaugo savo atsaką pakartojimui, API žinyne nurodo šią antraštę.
`GET`, `PUT`, `DELETE`	Nereikia: šiuos metodus pagal jų prasmę saugu kartoti. Antraštė priimama, bet nieko nekeičia.
`POST`, kuri tik skaito, pavyzdžiui, paieška, finansų ataskaitos ir `POST /v1/catalog/resolve`	Priimama, bet niekas neišsaugoma: užklausa tiesiog vykdoma iš naujo.

Kai kurias operacijas saugu kartoti net be antraštės:

PUT /v1/cards-by-external-id/{external_id} sukuria arba pakeičia kortelę su jūsų ID; pakartojimas su tuo pačiu turiniu nieko nekeičia.
Pasirinktinio šaltinio dokumentai identifikuojami pagal jūsų external_id; vėl išsiuntus tą patį dokumentą, grąžinama unchanged.
Srautu transliuojamas POST /v1/chat atsakymas vietoj antraštės naudoja turinio lauką request_id. Žr. Klausimų ir atsakymų boto kūrimas.

Saugūs pakartojimai

Derinkite raktą su pakartojimų taisyklėmis iš Klaidos: sukurkite raktą vieną kartą, prieš pirmąjį bandymą, ir siųskite jį su kiekvienu tos pačios operacijos bandymu.