ConverterHQDevelopers
API v1

Idempotencja i retry

Powtarzaj bez duplikowania kosztownej pracy ani side effects.

Błąd sieci jest niejednoznaczny: ConverterHQ może przyjąć request, mimo że klient nie dostał response. Create i handlers muszą być replay-safe.

Idempotentne create

Używaj tej samej Idempotency-Key tylko dla tej samej operacji logicznej i client_reference_id dla swojego ID biznesowego. Nie używaj key z innym body.

Retry transportu

Retryuj timeouty, resety, 429 i retryable 5xx z exponential backoff i jitter. Szanuj Retry-After; deterministycznych 4xx nie powtarzaj automatycznie.

Retry Tasks

Retry wykonania tworzy nową attempt i zachowuje poprzedni błąd. Udane upstream Tasks nie znikają, gdy ponawiasz tylko downstream branch.

Idempotencja webhooków

Zweryfikuj signature przed side effect, potem deduplikuj po event_id. Odpowiadaj szybko, wolną pracę przenieś do własnej kolejki.