Idempotency and retry safety
Safely retry document task creation across network timeouts using project-scoped Idempotency-Key headers, and distinguish these from paid process and provider dispatch.
Replay-safe task creation#
POST /v1/tasks accepts an optional Idempotency-Key (8–128 ASCII letters, digits, dots, underscores, colons or hyphens; starts with a letter or digit). Repeating a key for the same HQTools account and API project returns the existing task. Reusing the same key for a different tool returns 409 IDEMPOTENCY_KEY_REUSED.
curl -q --fail-with-body -X POST 'https://api.pdfhq.io/v1/tasks' \
-H 'x-api-key: YOUR_SERVER_SIDE_API_KEY' \
-H 'Idempotency-Key: job-20261025-00001' \
-H 'Content-Type: application/json' \
-d '{"tool":"compress"}'The returned task ID is stable across retries. Keys are scoped to an account and API project and remain associated with the task until the underlying record is purged. Create a new key for a new task.
Different retry rules for different resources#
Task creation: replay using the same Idempotency-Key after a network interruption. Task processing: the fixed task ID already provides backend job/credit idempotency for identical options; inspect its state before trying again. AI jobs: use a fresh user-approved quote and stable Idempotency-Key as supported by the AI endpoint. eSignature send: an uncertain provider response requires envelope reconciliation; do not blindly resend a signature request.
Signed S3 uploads use short-lived POST form policies. Do not send x-api-key or Idempotency-Key to S3. Storage uploads and quote estimation do not themselves charge credits; processing does.
