Idempotenti pieprasījumi

Pieprasījums var neizdoties pēc tam, kad Sursa darbu jau ir paveikusi: savienojums pārtrūkst vai jūsu process tiek restartēts, pirms pienāk atbilde. Ja vēlreiz nosūtīsiet to pašu POST, var tikt izveidota otra kartīte vai otrs webhook galapunkts. To novērš idempotences atslēga.

Ar katru POST un PATCH nosūtiet galveni Idempotency-Key. Ja Sursa jau ir saņēmusi pieprasījumu ar šo atslēgu, tā operāciju neizpilda vēlreiz, bet atgriež atbildi, ko saglabāja pirmajā reizē.

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

Atkārtots pieprasījums saņem tādu pašu statusu un saturu kā pirmais, ar papildu galveni:

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

Atkārtotajam pieprasījumam ir savs X-Request-Id.

Atslēgas izvēle

Katrai loģiskajai operācijai izmantojiet jaunu nejaušu vērtību, piemēram, UUID v4: „izveidot šo kartīti“, „reģistrēt šo webhook galapunktu“. Izmantojiet to pašu vērtību katrā šīs operācijas atkārtojumā un nekad – citai operācijai.
Laba atslēga ir atvasināta no jūsu pašu datiem, ja tādi ir, piemēram, sync-2026-10-24-record-1042. Tad pat restartēts darbs, kas zaudējis savu atmiņu, atkal nosūta to pašu atslēgu.
Atslēga ir no 1 līdz 255 drukājamām ASCII rakstzīmēm. Jebkas cits atgriež 400 ar kodu api.idempotency_key_invalid.

Ko Sursa dara ar atslēgu

Situācija	Atbilde
Pirmais pieprasījums ar šo atslēgu	Operācija tiek izpildīta kā parasti.
Tā pati atslēga, tas pats pieprasījums, pirmais beidzās ar `2xx` vai `4xx`	Saglabātā atbilde ar `Idempotency-Replayed: true`. Operācija netiek izpildīta vēlreiz.
Tā pati atslēga, pirmais pieprasījums vēl tiek izpildīts	`409` `api.idempotency_in_progress` ar `Retry-After: 1`. Nogaidiet un atkārtojiet.
Tā pati atslēga, cita metode, ceļš, `Content-Type` vai saturs	`409` `api.idempotency_mismatch`. Atslēgu jau aizņēmis cits pieprasījums.
Pirmais pieprasījums beidzās ar `5xx` vai `429`	Atslēga tiek atbrīvota: nākamais pieprasījums ar to izpilda operāciju vēlreiz.

Atslēga ir derīga 24 stundas. Pēc tam tā pati atslēga sāk jaunu operāciju.
Atslēgas ir atsevišķas katrai organizācijai un katram izsaucējam: divas dažādas API atslēgas var izmantot vienu un to pašu vērtību, neietekmējot viena otru.
Arī kļūdas atbilde ar 4xx tiek saglabāta. Pieprasījums ar validācijas kļūdu, atkārtots ar to pašu atslēgu, neizdodas tāpat; izlabojiet to un nosūtiet ar jaunu atslēgu.

Kuriem pieprasījumiem tā vajadzīga

Metode	Idempotency-Key
`POST`, `PATCH`	Nosūtiet to. Katrai operācijai, kas saglabā savu atbildi atkārtojumam, API rokasgrāmatā šī galvene ir norādīta.
`GET`, `PUT`, `DELETE`	Nav vajadzīga: šīs metodes pēc savas nozīmes ir droši atkārtojamas. Galvene tiek pieņemta, bet neko neietekmē.
`POST`, kas tikai lasa, piemēram, meklēšana, finanšu pārskati un `POST /v1/catalog/resolve`	Tiek pieņemta, bet nekas netiek saglabāts: pieprasījums vienkārši tiek izpildīts vēlreiz.

Dažas operācijas ir droši atkārtojamas arī bez galvenes:

PUT /v1/cards-by-external-id/{external_id} izveido vai aizstāj kartīti ar jūsu ID; atkārtojums ar to pašu saturu neko nemaina.
Pielāgota avota dokumentus identificē jūsu external_id; tā paša dokumenta atkārtota nosūtīšana atgriež unchanged.
POST /v1/chat straumētā atbilde galvenes vietā izmanto satura lauku request_id. Sk. Jautājumu un atbilžu robota izveide.

Droša atkārtošana

Apvienojiet atslēgu ar atkārtošanas noteikumiem no ceļveža Kļūdas: izveidojiet atslēgu vienreiz, pirms pirmā mēģinājuma, un sūtiet to ar katru tās pašas operācijas mēģinājumu.