Bezpieczne ponawianie
Gdy połączenie się zrywa, nie wiesz, czy zamówienie dotarło. Wyślij je więc ponownie: przez 7 dni ten sam klucz Idempotency-Key oznacza to samo zamówienie, a opłata jest pobierana raz.
Jak to działa
POST /orders wymaga nagłówka Idempotency-Key: do 200 znaków ASCII bez spacji, które wymyślasz i przechowujesz we własnym zapisie zamówienia. UUID dobrze się sprawdza. Do nowego zamówienia użyj nowego klucza Idempotency-Key.
curl -X POST "https://api.talismanleads.io/v1/orders" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Idempotency-Key: crm-export-2026-11-05" \
-H "Content-Type: application/json" \
-d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'Co otrzymasz w odpowiedzi
201 i nowe zamówienie.200, to samo zamówienie i Idempotent-Replay: true. Nie jest pobierana żadna dodatkowa opłata, nawet jeśli cena się od tego czasu zmieniła.order_status_unknown lub rate_limited.409 idempotency_conflict. Żadne zamówienie nie zostaje złożone.insufficient_balance409 price_changed, a nowy klucz Idempotency-Key składa zamówienie w nowej cenie.Gdy nie wiesz, co się stało
Każda utracona odpowiedź, order_status_unknown oraz odpowiedź niebędąca JSON-em, na przykład 502 lub 504 z bramy, oznaczają to samo: powtórz żądanie z tym samym kluczem Idempotency-Key, aby poznać faktyczny stan. To nigdy nie pobiera opłaty dwa razy. Nigdy nie twórz nowego klucza Idempotency-Key dlatego, że żądanie przekroczyło limit czasu lub się nie powiodło: to jest nowe zamówienie i opłata zostanie pobrana.
Między powtórzeniami odczekaj minutę. Jeśli po kilku minutach nadal otrzymujesz order_status_unknown, przerwij i skontaktuj się z pomocą techniczną, podając request_id. Nie twórz nowego klucza Idempotency-Key.
Jak długo obowiązuje klucz Idempotency-Key
Klucz Idempotency-Key jest pamiętany przez 7 dni od pierwszego wysłania. Później ten sam klucz składa nowe zamówienie, więc ponawiaj w ciągu kilku dni, a do każdego nowego zamówienia używaj nowego klucza Idempotency-Key.