Error Reference

When a request fails, PixDoc returns a JSON error response with a machine-readable code and a human-readable message.

Error Response Format

All errors follow the same structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {}
  }
}

The details object is optional and provides additional context when available (for example, a list of missing template variables or the current plan limit).

Error Codes

Code	HTTP Status	Description	Resolution
`AUTH_MISSING`	401	Authorization header missing or malformed	Add `Authorization: Bearer pd_live_...` header (or `?key=` for OG endpoints).
`AUTH_INVALID`	401	API key not found in database	Verify your API key is correct.
`AUTH_REVOKED`	401	API key has been revoked	Create a new API key in the dashboard.
`VALIDATION_ERROR`	400	Request body validation failed	Check required fields and types. Ensure exactly one of `html`, `url`, or `template_id` is provided.
`PLAN_LIMIT_EXCEEDED`	429	Monthly render limit exceeded (Free plan only). Paid plans allow overage at $0.01/render.	Upgrade to a paid plan for automatic overage billing, or wait for the monthly reset.
`RENDER_FAILED`	500	Rendering failed internally	Check your HTML for syntax errors. If the issue persists, try simplifying your content or contact support.
`RENDER_TIMEOUT`	408	Render exceeded the timeout limit	Simplify your HTML content, reduce external resource loading, or adjust the `timeout` option (max 60 seconds).
`RENDERER_UNAVAILABLE`	503	Rendering service is temporarily unavailable	Retry after a short delay. If persistent, check the status page.
`SSRF_BLOCKED`	400	URL points to a private or internal network	Use publicly accessible URLs only. Localhost, private IPs (10.x, 172.16.x, 192.168.x), and link-local addresses are blocked.
`TEMPLATE_NOT_FOUND`	404	Template ID or slug does not exist	Verify the template ID is a valid UUID, or the slug matches a template you own or a public template.

HTTP Status Codes

PixDoc uses the following HTTP status codes:

Status	Meaning
200	Success
201	Resource created (template creation)
400	Bad request: invalid input, SSRF blocked, or missing variables
401	Unauthorized: missing, invalid, or revoked API key
403	Forbidden: access denied
404	Not found: template or resource does not exist
408	Request timeout: render took too long
409	Conflict: duplicate template name
429	Too many requests: monthly render limit exceeded
502	Bad gateway: renderer service failed

Retry Recommendations

Not all errors should be retried. Use this guide:

Error Code	Retry?	Strategy
`AUTH_MISSING`	No	Add the Authorization header.
`AUTH_INVALID`	No	Check your API key.
`AUTH_REVOKED`	No	Create a new key in the dashboard.
`VALIDATION_ERROR`	No	Fix the request body before retrying.
`PLAN_LIMIT_EXCEEDED`	No	Wait for the monthly reset or upgrade your plan.
`RENDER_FAILED`	Yes	Wait 1-2 seconds and retry. If it fails repeatedly, check your HTML.
`RENDER_TIMEOUT`	Yes	Retry with a higher `timeout` value or simplified content.
`RENDERER_UNAVAILABLE`	Yes	Retry after 5-10 seconds.
`SSRF_BLOCKED`	No	Change the URL to a public address.
`TEMPLATE_NOT_FOUND`	No	Verify the template ID or slug.

For transient errors like RENDER_FAILED, use exponential backoff: wait 1 second, then 2 seconds, then 4 seconds between retries, up to a maximum of 3 attempts.

Common Troubleshooting

"Exactly one of html, url, or template_id must be provided"

You passed zero or more than one content source. Each render request accepts exactly one of:

html: raw HTML string
url: a public URL to render
template_id: a template UUID (PDF endpoint only)

Render times out but HTML works locally

The render environment has a default timeout of 30 seconds (15 seconds for OG images). Common causes of slow renders:

Loading external fonts or images from slow CDNs
JavaScript that runs indefinitely
Very large or deeply nested HTML documents

Try setting enableJavaScript: false if your content does not require it, or use the waitForSelector option instead of waitForTimeout for more reliable timing.

PixDoc blocks URLs that resolve to private IP ranges for security. If your target URL redirects to an internal address, that will also be blocked. Ensure the final destination is a publicly routable IP address.

Template variables not substituting

Make sure your variable names in {{variableName}} use only letters, numbers, and underscores. Spaces or special characters inside the braces will not be recognized as variables.