Idempotens kérések

Egy kérés akkor is meghiúsulhat, ha a Sursa már elvégezte a munkát: megszakad a kapcsolat, vagy a folyamatod újraindul, mielőtt a válasz megérkezne. Ha ugyanazt a POST kérést újra elküldöd, létrehozhatsz egy második kártyát vagy egy második webhookot. Ezt akadályozza meg az idempotenciakulcs: vele a kérés megismétlése nem futtatja le újra a műveletet.

Minden POST és PATCH kéréssel küldj Idempotency-Key fejlécet. Ha a Sursa már látott kérést ezzel a kulccsal, nem futtatja le újra a műveletet, hanem visszaadja az első alkalommal elmentett választ.

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

A megismételt kérés ugyanazt az állapotkódot és törzset kapja, mint az első, egy további fejléccel:

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

A megismételt kérésnek saját X-Request-Id azonosítója van.

Kulcs választása

Minden logikai művelethez használj új véletlen értéket, például UUID v4-et: „hozd létre ezt a kártyát”, „regisztráld ezt a webhookot”. Az adott művelet minden újrapróbálkozásához ugyanazt az értéket használd, és soha ne használd egy másik művelethez.
A jó kulcs a saját adataidból származik, ha vannak ilyenek, például sync-2026-10-24-record-1042. Így még egy olyan újraindult feladat is ugyanazt a kulcsot küldi el újra, amelynek elveszett a memóriája.
A kulcs 1–255 nyomtatható ASCII-karakterből áll. Minden más esetben a válasz 400 az api.idempotency_key_invalid kóddal.

Mit csinál a Sursa a kulccsal

Helyzet	Válasz
Az első kérés ezzel a kulccsal	A művelet a szokásos módon lefut.
Ugyanaz a kulcs, ugyanaz a kérés, az első `2xx` vagy `4xx` válasszal zárult	Az elmentett válasz `Idempotency-Replayed: true` fejléccel. A művelet nem fut le újra.
Ugyanaz a kulcs, az első kérés még fut	`409` `api.idempotency_in_progress` `Retry-After: 1` fejléccel. Várj, és próbáld újra.
Ugyanaz a kulcs, de más metódus, útvonal, `Content-Type` vagy törzs	`409` `api.idempotency_mismatch`. A kulcsot már egy másik kérés foglalja.
Az első kérés `5xx` vagy `429` válasszal zárult	A kulcs felszabadul: a következő vele küldött kérés újra lefuttatja a műveletet.

Egy kulcs 24 óráig érvényes. Ezután ugyanaz a kulcs új műveletet indít.
A kulcsok szervezetenként és hívónként külön kezelődnek: két különböző API-kulcs ugyanazt az értéket is használhatja anélkül, hogy egymást befolyásolnák.
A 4xx hibaválasz is elmentődik. Az érvényesítésen elbukott kérés ugyanígy bukik el, ha ugyanazzal a kulccsal megismétled; javítsd ki, és küldd el új kulccsal.

Mely kérésekhez kell

Metódus	Idempotency-Key
`POST`, `PATCH`	Küldd el. Az API-referencia minden olyan végpontnál feltünteti a fejlécet, amely az ismétléshez elmenti a válaszát.
`GET`, `PUT`, `DELETE`	Nincs rá szükség: ezek a metódusok jellegüknél fogva biztonságosan megismételhetők. A fejlécet a Sursa elfogadja, de nincs hatása.
Csak olvasó `POST`, például a keresés, a pénzügyi jelentések és a `POST /v1/catalog/resolve`	A Sursa elfogadja, de semmit nem ment el: a kérés egyszerűen újra lefut.

Néhány művelet a fejléc nélkül is biztonságosan megismételhető:

A PUT /v1/cards-by-external-id/{external_id} létrehozza vagy lecseréli a kártyát a te azonosítóddal; az azonos tartalmú ismétlés semmit nem változtat.
Az egyéni források dokumentumait a te external_id értéked azonosítja; ugyanannak a dokumentumnak az újraküldése unchanged eredményt ad.
A POST /v1/chat adatfolyamként érkező válasza a fejléc helyett a törzs request_id mezőjét használja. Lásd: Kérdés-válasz bot készítése.

Biztonságos újrapróbálkozás

A kulcsot a Hibák útmutató újrapróbálási szabályaival együtt használd: a kulcsot egyszer, az első kísérlet előtt hozd létre, és ugyanannak a műveletnek minden kísérletével küldd el.