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

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

Уз сваки POST и PATCH пошаљите заглавље Idempotency-Key. Ако је 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 у телу. Погледајте Израда бота за питања и одговоре.

Безбедни поновни покушаји

Комбинујте кључ са правилима за поновне покушаје из водича Грешке: кључ креирајте једном, пре првог покушаја, и шаљите га уз сваки покушај исте операције.