Error Codes

PDFik uses standard HTTP response codes to indicate the success or failure of API requests.

Error Response Format

Errors follow the RFC 7807 Problem Details format, with a type link back to this page and a descriptive detail field:

{
  "type": "https://docs.pdfik.net/error-codes#401",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid API key"
}

Reference Table

Webhook / job error codes

These values appear in the error_code field of a failed job status or failure webhook:

General API Errors

The RFC 7807 type URLs below are returned by the submission and platform endpoints and link directly to the matching section on this page.

quota-exceeded

HTTP 402 — https://docs.pdfik.net/error-codes#quota-exceeded

Your account has used all of its monthly PDF generation quota for the current billing window. The response carries plan, limit and used fields.

Remediation: wait for the quota reset or upgrade your plan on the Billing page. Test mode ("test": true) does not consume this quota — integration tests keep working.

concurrency-limit

HTTP 429, Retry-After: 5 — https://docs.pdfik.net/error-codes#concurrency-limit

You already have as many jobs queued or rendering as your plan allows at a time (compare in_flight and limit in the response). This is a throttle, not a billing state — new work is accepted as soon as your in-flight jobs drain.

Remediation: poll your pending jobs and resubmit, or spread submissions out. If you consistently need more parallelism, upgrade your plan.

validation-error

HTTP 422 — https://docs.pdfik.net/error-codes#validation-error

The request body failed schema validation. detail is a list of per-field errors with loc, msg and type.

Remediation: fix the listed fields — compare against the request references for URL-to-PDF and HTML-to-PDF.

403 Forbidden

HTTP 403 — https://docs.pdfik.net/error-codes#403

The credentials are recognized but this request is not allowed. The most common customer-visible cause is an IP whitelist on the API key (IP_NOT_WHITELISTED): the calling server's address is not in the allowed ranges.

Remediation: update the key's IP whitelist in the dashboard API settings, or call from a whitelisted address.

500 Internal Server Error

HTTP 500 — https://docs.pdfik.net/error-codes#500

An unexpected error occurred inside PDFik.

Remediation: retry with backoff. If it persists, contact [email protected] with the approximate time and the request that failed.

service-unavailable

HTTP 503, Retry-After: 5 — https://docs.pdfik.net/error-codes#service-unavailable

A backing service that enforces limits (rate-limit, quota or download counters) is temporarily unreachable. PDFik fails closed rather than serving requests with limits disabled.

Remediation: retry after the interval in the Retry-After header.

Other HTTP statuses

A type URL ending in a bare status number (#401, #404, #409, …) is the generic RFC 7807 envelope for a standard HTTP error. The specific reason is in the response's title and detail fields, and the Reference Table above maps each status and code to a fix.

Storage & Download Errors

The RFC 7807 type URLs below are returned by the quota, rendering, and download endpoints and link directly to the matching section on this page.

quota-bytes-exceeded

HTTP 429 — https://docs.pdfik.net/error-codes#quota-bytes-exceeded

Your account has generated more PDF data (in bytes) than your plan's monthly generated-volume quota allows for the current billing window (0.5 GB on Free, 10 GB on Starter, 50 GB on Pro, 300 GB on Business). The byte quota counts generated output only — downloading a file never debits it.

Remediation: wait for the billing window to reset, upgrade your plan, or — on the Business plan — purchase additional +1 GB/month volume blocks from the Billing page. See Rate Limits & Quotas for the full table.

file-too-large

Job error code FILE_TOO_LARGE — https://docs.pdfik.net/error-codes#file-too-large

The rendered PDF exceeded the maximum per-file size (150 MB on all plans by default). The job is marked failed and the file is not stored; the error appears in the job status error_code field and in the failure webhook.

Remediation: reduce the page's asset weight (images are the usual culprit), enable compression options (Pro+), or split the document. If you genuinely need files larger than 150 MB, contact [email protected] — the limit can be raised per account.

download-busy

HTTP 429, Retry-After: 10 — https://docs.pdfik.net/error-codes#download-busy

Another download stream of this file is active right now — only one active stream per file is allowed. This check runs before the attempt counter, so a busy rejection never consumes one of your download attempts: if two of your workers race for the same file, the duplicate is deduplicated for free.

Remediation: retry after the running stream finishes (the Retry-After header suggests 10 seconds). If you see this often, your code is fetching the same file concurrently — deduplicate on job_id on your side.

download-attempts-exhausted

HTTP 429, Retry-After: 3600 — https://docs.pdfik.net/error-codes#download-attempts-exhausted

Each generated file can be downloaded at most 3 times. An attempt is counted when the stream starts, not when it completes — an interrupted download still consumes an attempt.

Remediation: store the PDF on your side after the first successful download (the production pattern). If the attempts are exhausted, re-render the document or contact [email protected] to reset the counter.

download-limit-exceeded (replaced)

This code was split on 2026-08-04 into the two states it used to conflate: download-busy (wait seconds) and download-attempts-exhausted (attempts gone). Update any matcher on the old type URL to the two new codes.

sandbox-rate-limit

HTTP 429 — https://docs.pdfik.net/error-codes#sandbox-rate-limit

The no-account sandbox allows a few watermarked renders per visitor per day and has a global daily capacity. When either cap is reached, the sandbox answers 429 with a Retry-After header.

Remediation: sign up — the Free plan includes 100 real renders per month, without the sandbox watermark.

sandbox-verification-failed

HTTP 403 — https://docs.pdfik.net/error-codes#sandbox-verification-failed

The sandbox requires passing an anti-bot verification (Cloudflare Turnstile) before rendering. The token was missing, expired, or invalid.

Remediation: reload the page and try again; make sure the Turnstile widget completed before submitting.

test-rate-limit-exceeded

HTTP 429 — https://docs.pdfik.net/error-codes#test-rate-limit-exceeded

Test-mode submissions ("test": true) are free — they do not consume the PDF or data-volume quota — but they are capped per account (60 per minute and 2,000 per day by default) as an abuse brake. The response's window field says which cap was hit; Retry-After says when it resets.

Remediation: slow down your test loop or batch your integration tests. If your CI legitimately needs a higher cap, contact [email protected].

file-expired

HTTP 410 — https://docs.pdfik.net/error-codes#file-expired

Generated PDFs are available for download for 24 hours after generation (expires_at in the job status and webhook payload); files are physically deleted within 48 hours. After expires_at, the download endpoint returns 410 Gone.

Remediation: download and persist the file within the 24-hour window (the expires_at timestamp tells you exactly when it lapses). An expired file cannot be recovered — submit the job again to re-render it.