ConverterHQDevelopers
Documentation

Idempotency and retries

Retry safely without duplicating expensive conversion work or downstream side effects.

Network failures are ambiguous: a request can succeed on ConverterHQ even when your client never receives the response. Design every production integration for safe replay.

Idempotent creates

Send a stable idempotency key for create operations when the endpoint supports it. Reuse the same key only for the same logical request. Also set client_reference_id when you need a durable link to your own order, document or workflow identifier.

Idempotent create
Idempotency-Key: invoice-92184-pdf-v1

{
  "client_reference_id": "invoice-92184",
  "tasks": { "...": "..." }
}

Transport retries

Retry connection resets, timeouts and retryable 5xx/429 responses with exponential backoff and jitter. Respect Retry-After. Do not automatically retry deterministic 4xx validation failures.

Job and Task retries

Transport retry and execution retry are different. A user-triggered Task retry creates a new attempt and preserves the previous failure for diagnostics. Retrying a failed downstream Task should not silently erase successful upstream work.

Webhook idempotency

Webhook delivery is at least once. Verify the signature first, then deduplicate by event ID before committing business side effects. A successful handler should return quickly and move slow work to your own queue.