Żądania idempotentne

Żądanie może się nie powieść, gdy Sursa już wykonała pracę: połączenie się zrywa albo Twój proces uruchamia się ponownie, zanim dotrze odpowiedź. Jeśli ponownie wyślesz ten sam POST, możesz utworzyć drugą kartę lub drugi webhook. Zapobiega temu klucz idempotencji.

Wysyłaj nagłówek Idempotency-Key z każdym żądaniem POST i PATCH. Jeśli Sursa widziała już żądanie z tym kluczem, nie wykonuje operacji ponownie: zwraca odpowiedź zapisaną za pierwszym razem.

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

Powtórzone żądanie otrzymuje ten sam status i tę samą treść co pierwsze, z dodatkowym nagłówkiem:

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

Powtórzone żądanie ma własny X-Request-Id.

Wybór klucza

Używaj nowej losowej wartości, np. UUID v4, dla każdej operacji logicznej: „utwórz tę kartę”, „zarejestruj ten webhook”. Używaj tej samej wartości przy każdym ponowieniu tej operacji i nigdy przy innej operacji.
Dobry klucz wywodzi się z Twoich własnych danych, jeśli je masz, np. sync-2026-10-24-record-1042. Wtedy nawet ponownie uruchomione zadanie, które straciło swój stan, wyśle ten sam klucz.
Klucz ma od 1 do 255 drukowalnych znaków ASCII. Każda inna wartość zwraca 400 z kodem api.idempotency_key_invalid.

Co Sursa robi z kluczem

Sytuacja	Odpowiedź
Pierwsze żądanie z tym kluczem	Operacja wykonuje się normalnie.
Ten sam klucz, to samo żądanie, pierwsze zakończyło się statusem `2xx` lub `4xx`	Zapisana odpowiedź z `Idempotency-Replayed: true`. Operacja nie jest wykonywana ponownie.
Ten sam klucz, pierwsze żądanie jest wciąż wykonywane	`409` `api.idempotency_in_progress` z `Retry-After: 1`. Odczekaj i ponów żądanie.
Ten sam klucz, inna metoda, ścieżka, `Content-Type` lub treść	`409` `api.idempotency_mismatch`. Klucz jest już zajęty przez inne żądanie.
Pierwsze żądanie zakończyło się statusem `5xx` lub `429`	Klucz zostaje zwolniony: następne żądanie z tym kluczem ponownie wykonuje operację.

Klucz jest ważny przez 24 godziny. Po tym czasie ten sam klucz rozpoczyna nową operację.
Klucze są oddzielne dla każdej organizacji i każdego wywołującego: dwa różne klucze API mogą używać tej samej wartości bez wzajemnego wpływu.
Odpowiedź z błędem 4xx również jest zapisywana. Żądanie, które nie przeszło walidacji, po powtórzeniu z tym samym kluczem kończy się tak samo; popraw je i wyślij z nowym kluczem.

Które żądania go potrzebują

Metoda	Idempotency-Key
`POST`, `PATCH`	Wysyłaj go. Każda operacja, która zapisuje swoją odpowiedź na wypadek powtórzenia, wymienia ten nagłówek w dokumentacji API.
`GET`, `PUT`, `DELETE`	Niepotrzebny: te metody z założenia można bezpiecznie powtarzać. Nagłówek jest akceptowany i nie ma żadnego skutku.
`POST`, który tylko odczytuje dane, np. wyszukiwanie, raporty finansowe i `POST /v1/catalog/resolve`	Akceptowany, ale nic nie jest zapisywane: żądanie po prostu wykonuje się ponownie.

Niektóre operacje można bezpiecznie powtarzać nawet bez nagłówka:

PUT /v1/cards-by-external-id/{external_id} tworzy lub zastępuje kartę z Twoim identyfikatorem; powtórzenie z tą samą treścią niczego nie zmienia.
Dokumenty własnego źródła są identyfikowane przez Twój external_id; ponowne wysłanie tego samego dokumentu zwraca unchanged.
Strumieniowana odpowiedź POST /v1/chat zamiast nagłówka używa pola request_id w treści żądania. Zob. Zbuduj bota odpowiadającego na pytania.

Bezpieczne ponawianie

Połącz klucz z zasadami ponawiania z przewodnika Błędy: utwórz klucz raz, przed pierwszą próbą, i wysyłaj go z każdą próbą tej samej operacji.