PDFHQ logo

Documents

DocumentationGetting started

API errors and retries

Structured error responses, idempotency and recovery of asynchronous processing.

Server-side API keys Signed storage uploads

Predictable HTTP failures#

401/403 indicates authentication or entitlement failure. 404 hides inaccessible objects. 409 signals immutable settings, already-used uploads or invalid task state. 413 enforces size limits, 422 validates settings, and 429 is rate/concurrency limiting.

Transient commercial-service or queue failures return 503. Retry processing with the same task ID and identical options, using exponential backoff and a bounded retry budget.

Recovery example#

cURL
# Safe repeated processing attempt for the SAME task and options
curl -X POST https://api.pdfhq.io/v1/tasks/TASK_ID/process \
  -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"options":{"compression_level":"recommended"}}'

A failed processing task cannot be reversed by simply deleting the task. Consult account usage and support when investigating settlement discrepancies.

PDFHQ logo

PDF tools and document intelligence. Prepare, understand and work with your documents.

© 2026 PDFHQ. All rights reserved.