Idempotentní požadavky

Požadavek může selhat až poté, co Sursa práci už provedla: spojení se přeruší nebo se váš proces restartuje dřív, než odpověď dorazí. Když pak stejný POST odešlete znovu, může vzniknout druhá karta nebo druhý webhook. Tomu zabrání klíč idempotence.

S každým POST a PATCH odešlete hlavičku Idempotency-Key. Pokud Sursa požadavek s tímto klíčem už viděla, operaci znovu nespustí: vrátí odpověď, kterou si uložila poprvé.

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

Opakovaný požadavek dostane stejný stavový kód a tělo jako první, s jednou hlavičkou navíc:

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

Opakovaný požadavek má vlastní X-Request-Id.

Volba klíče

Pro každou logickou operaci použijte novou náhodnou hodnotu, například UUID v4: „vytvořit tuto kartu“, „zaregistrovat tento webhook“. Stejnou hodnotu použijte pro každé opakování této operace a nikdy pro jinou operaci.
Dobrý klíč je odvozený z vašich vlastních dat, pokud je máte, například sync-2026-10-24-record-1042. Pak i restartovaná úloha, která přišla o svou paměť, odešle znovu stejný klíč.
Klíč má 1 až 255 tisknutelných znaků ASCII. Cokoli jiného vrátí 400 s kódem api.idempotency_key_invalid.

Co Sursa s klíčem udělá

Situace	Odpověď
První požadavek s tímto klíčem	Operace proběhne jako obvykle.
Stejný klíč, stejný požadavek, první skončil s `2xx` nebo `4xx`	Uložená odpověď s `Idempotency-Replayed: true`. Operace znovu neproběhne.
Stejný klíč, první požadavek stále běží	`409` `api.idempotency_in_progress` s `Retry-After: 1`. Počkejte a zopakujte.
Stejný klíč, jiná metoda, cesta, `Content-Type` nebo tělo	`409` `api.idempotency_mismatch`. Klíč už obsadil jiný požadavek.
První požadavek skončil s `5xx` nebo `429`	Klíč se uvolní: další požadavek s ním operaci spustí znovu.

Klíč platí 24 hodin. Poté stejný klíč spustí novou operaci.
Klíče jsou oddělené pro každou organizaci a každého volajícího: dva různé klíče API mohou použít stejnou hodnotu, aniž by se navzájem ovlivnily.
Ukládá se i chybová odpověď s 4xx. Požadavek, který neprošel validací, při opakování se stejným klíčem selže stejně; opravte ho a odešlete s novým klíčem.

Které požadavky ho potřebují

Metoda	Idempotency-Key
`POST`, `PATCH`	Odešlete ho. Každá operace, která si odpověď ukládá pro opakování, uvádí tuto hlavičku v referenci API.
`GET`, `PUT`, `DELETE`	Není potřeba: tyto metody lze už ze své podstaty bezpečně opakovat. Hlavička se přijme, ale nic nezmění.
`POST`, který jen čte, například vyhledávání, finanční výkazy a `POST /v1/catalog/resolve`	Přijme se, ale nic se neuloží: požadavek prostě proběhne znovu.

Některé operace lze bezpečně opakovat i bez hlavičky:

PUT /v1/cards-by-external-id/{external_id} vytvoří nebo nahradí kartu s vaším identifikátorem; opakování se stejným obsahem nic nezmění.
Dokumenty vlastního zdroje jsou klíčované vaším external_id; opětovné odeslání stejného dokumentu vrátí unchanged.
Streamovaná odpověď POST /v1/chat používá místo hlavičky pole request_id v těle. Viz Vytvořte bota pro otázky a odpovědi.

Bezpečné opakování

Kombinujte klíč s pravidly opakování ze stránky Chyby: klíč vytvořte jednou, před prvním pokusem, a odesílejte ho s každým pokusem téže operace.