Errors

The PDFox API uses standard HTTP status codes. Every error response includes a machine-readable code and a human-readable message.

HTTP status codes

Status	Meaning
`200`	Success
`400`	Bad request — invalid or missing parameters
`401`	Unauthenticated — missing or invalid API key
`403`	Forbidden — key lacks permission or is revoked
`404`	Not found — resource doesn't exist or belongs to another org
`402`	Insufficient credits
`429`	Rate limit exceeded
`500`	Internal server error — something went wrong on our end

Error codes

Code	Description
`validation_error`	Request body failed schema validation
`template_not_found`	The template ID doesn't exist in your org
`insufficient_credits`	Your org has run out of credits
`job_not_found`	Job ID doesn't exist or belongs to another org
`render_failed`	The PDF render itself failed — check your template HTML
`rate_limit_exceeded`	Too many requests — back off and retry

500 errors are transient. Retry with exponential back-off starting at 1 second. If errors persist for more than a few minutes, check status.pdfox.com.

Rate limits

Limits are enforced per API key. When you hit 429, the response includes a Retry-After header with the number of seconds to wait before retrying.

{
  "error": {
    "code": "validation_error",
    "message": "templateId is required",
    "details": [
      { "field": "templateId", "issue": "Required" }
    ]
  }
}