Docs

Safe retries and idempotency

Retry URL and asynchronous jobs without charging twice for the same accepted request.

Choose a key

Send Idempotency-Key with a URL or async response request. Use 1–128 printable ASCII characters. Keys are scoped to the account. Keep the same body, response mode, and JSON key order when retrying; do not reuse a key for changed input.

curl

curl https://api.relaypdf.com/v1/pdf \
  -H "Authorization: Bearer $RELAYPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-2026-001" \
  --data '{"html":"<h1>Invoice</h1>","response":"async"}'

Handle the outcome

The same account, key, and request reuse the existing job. A changed request returns 409. A failed job needs a new key to start new work. Binary responses do not support idempotency keys; use URL/async and then download the result.

Retention and recovery

Keys are currently retained with job records. Retrying does not extend the output’s 24-hour lifetime. Poll GET /v1/jobs/:id after a timeout instead of creating a fresh job. Infrastructure retries can repeat compute, but successful settlement is idempotent.

Retry policy

Honor Retry-After on rate limits. Retry transient 5xx/network failures with bounded exponential backoff and the same key. Fix invalid inputs before retrying 400/413. Resolve available-credit or spending-cap issues for 402. Deduplicate webhook events by their stable event identity.

Docs hub →Node.js SDK →Playground →