API errors and retries
Structured error responses, idempotency and recovery of asynchronous processing.
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#
# 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.
