Ідемпотентні запити

Запит може завершитися помилкою вже після того, як 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} створює або замінює картку з вашим ідентифікатором; повтор із тим самим вмістом нічого не змінює.
Документи власного джерела ідентифікуються вашим external_id; повторне надсилання того самого документа повертає unchanged.
Потокова відповідь POST /v1/chat використовує поле request_id у тілі замість заголовка. Див. Створіть бота запитань і відповідей.

Безпечні повтори

Поєднуйте ключ із правилами повторів зі сторінки Помилки: створіть ключ один раз, перед першою спробою, і надсилайте його з кожною спробою тієї самої операції.