Идемпотентни заявки

Заявката може да се провали, след като Sursa вече е свършила работата: връзката прекъсва или процесът ви се рестартира, преди да пристигне отговорът. Ако изпратите същата заявка POST отново, може да създадете втора карта или втори уебхук. Ключът за идемпотентност предотвратява това.

Изпращайте заглавка Idempotency-Key с всяка заявка POST и PATCH. Ако Sursa вече е видяла заявка с този ключ, тя не изпълнява операцията отново, а връща отговора, който е запазила първия път.

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

Повторената заявка получава същия статус и същото тяло като първата, с една допълнителна заглавка:

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

Повторената заявка има собствен X-Request-Id.

Избор на ключ

Използвайте нова случайна стойност, например UUID v4, за всяка логическа операция: „създай тази карта“, „регистрирай този уебхук“. Използвайте една и съща стойност за всеки повторен опит на тази операция и никога за друга операция.
Добрият ключ се извлича от собствените ви данни, когато имате такива, например sync-2026-10-24-record-1042. Тогава дори рестартирано задание, което е загубило паметта си, изпраща отново същия ключ.
Ключът е от 1 до 255 печатими ASCII знака. Всичко друго връща 400 с кода api.idempotency_key_invalid.

Какво прави Sursa с ключа

Ситуация	Отговор
Първа заявка с този ключ	Операцията се изпълнява както обикновено.
Същият ключ, същата заявка, първата е завършила с `2xx` или `4xx`	Запазеният отговор, с `Idempotency-Replayed: true`. Операцията не се изпълнява отново.
Същият ключ, първата заявка все още се изпълнява	`409` `api.idempotency_in_progress` с `Retry-After: 1`. Изчакайте и опитайте отново.
Същият ключ, различен метод, път, `Content-Type` или тяло	`409` `api.idempotency_mismatch`. Ключът вече е зает от друга заявка.
Първата заявка е завършила с `5xx` или `429`	Ключът се освобождава: следващата заявка с него изпълнява операцията отново.

Ключът е валиден 24 часа. След това същият ключ започва нова операция.
Ключовете са отделни за всяка организация и за всеки извикващ: два различни API ключа може да използват една и съща стойност, без да си влияят.
Отговор с грешка 4xx също се запазва. Заявка, която не е преминала валидирането, се проваля по същия начин, когато се повтори със същия ключ; поправете я и я изпратете с нов ключ.

Кои заявки се нуждаят от него

Метод	Idempotency-Key
`POST`, `PATCH`	Изпращайте го. Всяка операция, която запазва отговора си за повторение, посочва заглавката в справочника на API.
`GET`, `PUT`, `DELETE`	Не е нужен: по своята природа тези методи може безопасно да се повтарят. Заглавката се приема и няма действие.
`POST`, който само чете, например търсене, финансовите отчети и `POST /v1/catalog/resolve`	Приема се, но нищо не се запазва: заявката просто се изпълнява отново.

Някои операции може безопасно да се повтарят дори без заглавката:

PUT /v1/cards-by-external-id/{external_id} създава или заменя картата с вашето ID; повторение със същото съдържание не променя нищо.
Документите на собствен източник се разпознават по вашия external_id; повторното изпращане на същия документ връща unchanged.
Отговорът в поток на POST /v1/chat използва полето request_id в тялото вместо заглавката. Вж. Създаване на бот за въпроси и отговори.

Безопасни повторни опити

Съчетайте ключа с правилата за повторни опити от Грешки: създайте ключа веднъж, преди първия опит, и го изпращайте с всеки опит на същата операция.