Idempotentné požiadavky

Požiadavka môže zlyhať až potom, ako Sursa prácu už vykonala: spojenie sa preruší alebo sa váš proces reštartuje skôr, než príde odpoveď. Ak rovnaký POST odošlete znova, môžete vytvoriť druhú kartu alebo druhý webhook. Tomu zabráni kľúč idempotencie.

S každou požiadavkou POST a PATCH odošlite hlavičku Idempotency-Key. Ak už Sursa požiadavku s týmto kľúčom videla, operáciu znova nevykoná: vráti odpoveď, ktorú si uložila prvýkrát.

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žiadavka dostane rovnaký stav a telo ako prvá, s jednou hlavičkou navyše:

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

Opakovaná požiadavka má vlastné X-Request-Id.

Výber kľúča

Pre každú logickú operáciu použite novú náhodnú hodnotu, napríklad UUID v4: „vytvoriť túto kartu“, „zaregistrovať tento webhook“. Rovnakú hodnotu použite pri každom opakovaní tejto operácie a nikdy pri inej.
Dobrý kľúč je odvodený z vašich vlastných údajov, ak nejaké máte, napríklad sync-2026-10-24-record-1042. Potom aj reštartovaná úloha, ktorá stratila pamäť, odošle znova ten istý kľúč.
Kľúč má 1 až 255 tlačiteľných znakov ASCII. Čokoľvek iné vráti 400 s kódom api.idempotency_key_invalid.

Čo Sursa s kľúčom urobí

Situácia	Odpoveď
Prvá požiadavka s týmto kľúčom	Operácia sa vykoná ako zvyčajne.
Rovnaký kľúč, rovnaká požiadavka, prvá skončila s `2xx` alebo `4xx`	Uložená odpoveď s `Idempotency-Replayed: true`. Operácia sa znova nevykoná.
Rovnaký kľúč, prvá požiadavka ešte prebieha	`409` `api.idempotency_in_progress` s `Retry-After: 1`. Počkajte a zopakujte.
Rovnaký kľúč, iná metóda, cesta, `Content-Type` alebo telo	`409` `api.idempotency_mismatch`. Kľúč už použila iná požiadavka.
Prvá požiadavka skončila s `5xx` alebo `429`	Kľúč sa uvoľní: ďalšia požiadavka s ním operáciu vykoná znova.

Kľúč platí 24 hodín. Potom ten istý kľúč spustí novú operáciu.
Kľúče sú oddelené pre každú organizáciu a každého volajúceho: dva rôzne kľúče API môžu používať rovnakú hodnotu bez toho, aby sa navzájom ovplyvňovali.
Uloží sa aj chybová odpoveď 4xx. Požiadavka, ktorá neprešla validáciou, pri opakovaní s rovnakým kľúčom zlyhá rovnako; opravte ju a odošlite s novým kľúčom.

Ktoré požiadavky ho potrebujú

Metóda	Idempotency-Key
`POST`, `PATCH`	Odošlite ho. Každá operácia, ktorá si odpoveď ukladá pre opakovanie, uvádza túto hlavičku v referencii API.
`GET`, `PUT`, `DELETE`	Netreba: tieto metódy možno svojou podstatou bezpečne opakovať. Hlavička sa prijme a nemá žiadny účinok.
`POST`, ktorý len číta, napríklad vyhľadávanie, finančné prehľady a `POST /v1/catalog/resolve`	Prijme sa, ale nič sa neuloží: požiadavka sa jednoducho vykoná znova.

Niektoré operácie možno bezpečne opakovať aj bez tejto hlavičky:

PUT /v1/cards-by-external-id/{external_id} vytvorí alebo nahradí kartu s vaším identifikátorom; opakovanie s rovnakým obsahom nič nezmení.
Dokumenty vlastného zdroja sú kľúčované vaším external_id; opätovné odoslanie rovnakého dokumentu vráti unchanged.
Streamovaná odpoveď POST /v1/chat používa namiesto hlavičky pole request_id v tele. Pozri Vytvorte bota na otázky a odpovede.

Bezpečné opakovanie

Kľúč kombinujte s pravidlami opakovania z návodu Chyby: kľúč vytvorte raz, pred prvým pokusom, a odošlite ho s každým pokusom o tú istú operáciu.