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.