Errors

The PDFox API uses standard HTTP status codes. Error responses are flat JSON with a human-readable error message and, on almost all client errors, a machine-readable code. Validation errors also include per-field details.

HTTP status codes

Status	Meaning
`200` / `202`	Success (`202` when a job is queued)
`400`	Bad request — invalid parameters (`VALIDATION_ERROR`) or malformed JSON (`INVALID_JSON`)
`401`	Unauthenticated — missing, invalid or revoked API key
`402`	Asset uploads only — your plan's asset count or storage limit is reached. PDF generation never returns 402; out of credits is a `422`
`403`	Forbidden — key lacks the required scope, `orgId` doesn't match the key (`ORG_MISMATCH`), or the account email isn't verified (`EMAIL_NOT_VERIFIED`)
`404`	Not found — resource doesn't exist or belongs to another org
`413`	Request body larger than 100 KB (no `code`)
`422`	Request is valid but can't be processed — out of credits, quota reached, or the job/template is in the wrong state
`429`	Rate limit exceeded (no `code`)
`500`	Internal server error — something went wrong on our end
`503`	Maintenance mode — generation is paused (no `code`)

Error codes

Code	Status	Description
`INVALID_JSON`	`400`	Request body isn't valid JSON
`VALIDATION_ERROR`	`400`	Request failed schema validation — see `details`
`UNAUTHORIZED`	`401`	Missing, invalid or revoked API key
`FORBIDDEN`	`403`	Credential isn't allowed to perform this action
`ORG_MISMATCH`	`403`	`orgId` doesn't match the credential's organisation
`EMAIL_NOT_VERIFIED`	`403`	The account's email address must be verified first
`NOT_FOUND`	`404`	Template, job or document doesn't exist in your org
`QUOTA_EXCEEDED`	`422`	Your org has run out of credits (plan allowance and credit packs)
`DAILY_QUOTA_EXCEEDED`	`422`	Your plan's daily PDF limit has been reached
`RETENTION_LIMIT_EXCEEDED`	`422`	`meta.retentionSeconds` is longer than your plan allows
`TEMPLATE_SCHEMA_INVALID`	`422`	Payload validation is on for the template but its published JSON Schema can't be compiled
`NO_PUBLISHED_VERSION`	`422`	The template has never been published
`TEMPLATE_DISABLED`	`422`	The template is disabled
`JOB_NOT_COMPLETED`	`422`	The job is still queued or processing, so there's nothing to download yet
`JOB_FAILED`	`422`	The job failed, so there's no PDF — the message is the job's error
`JOB_NOT_FAILED`	`422`	Only failed jobs can be retried

A failed render doesn't produce an HTTP error: the job's status becomes failed and the reason is in its errorMessage. See Check job status.

500 and 503 errors are transient. Retry with exponential back-off starting at 1 second. If errors persist for more than a few minutes, contact support.

Rate limits

The API allows 300 requests per minute per credential (per Authorization header value). Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets) headers. When you hit 429, the response also includes a Retry-After header (seconds), and the body's retryAfter is an ISO 8601 timestamp of when you can retry.

HTTP/1.1 400 Bad Request
{
  "error": "Validation failed.",
  "code": "VALIDATION_ERROR",
  "details": [
    { "field": "templateId", "message": "Invalid uuid" }
  ]
}

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 300
RateLimit-Remaining: 0
RateLimit-Reset: 34
Retry-After: 34

{
  "error": "Rate limit exceeded.",
  "retryAfter": "2026-05-17T10:01:00.000Z"
}

HTTP/1.1 503 Service Unavailable
{
  "error": "...",
  "maintenanceWindow": { "from": "...", "to": "..." }
}