Errors

Error format

PDFBase uses conventional HTTP status codes and returns errors as JSON with a consistent structure.

{
  "error": {
    "type": "invalid_request",
    "code": "html_too_large",
    "message": "HTML body exceeds the 5MB limit. Current size: 7.2MB.",
    "param": "html",
    "doc_url": "https://docs.pdfbase.dev/errors#html_too_large"
  }
}

Field	Type	Description
`type`	string	Error category. Always present.
`code`	string	Machine-readable error code. Always present.
`message`	string	Human-readable explanation. Always present.
`param`	string \| null	The parameter that caused the error, if applicable.
`doc_url`	string	Link to documentation for this specific error.

HTTP status codes

Status	Meaning
`200`	Success
`201`	Created
`400`	Bad request — invalid parameters
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — key lacks required scope or IP not allowed
`404`	Not found — resource doesn’t exist or has expired
`402`	Payment required — credit balance is 0
`409`	Conflict — idempotency key reuse with different parameters
`413`	Payload too large — HTML or file exceeds size limit
`422`	Unprocessable — valid JSON but semantically wrong (e.g., template schema mismatch)
`429`	Rate limited — too many requests
`500`	Internal error — our fault, not yours
`503`	Service unavailable — temporary capacity issue

Error types

`invalid_request`

The request was malformed or missing required fields.

{
  "error": {
    "type": "invalid_request",
    "code": "missing_required_field",
    "message": "The 'html' or 'url' field is required when creating a PDF.",
    "param": "html"
  }
}

`authentication_error`

API key is missing, invalid, revoked, or expired.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is not valid. Check that you're using the correct key for this environment.",
    "param": null
  }
}

`permission_error`

The API key is valid but doesn’t have the required scope, or the request IP isn’t allowed.

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This key requires the 'templates:write' scope to create templates.",
    "param": null
  }
}

`not_found`

The requested resource doesn’t exist or has expired (files expire after 24h by default).

{
  "error": {
    "type": "not_found",
    "code": "resource_expired",
    "message": "PDF 'pdf_x7Kf9m' has expired. Files are deleted 24 hours after creation.",
    "param": null
  }
}

`rate_limit_error`

You’ve exceeded your plan’s rate limit. See Rate Limits for details.

{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_requests",
    "message": "Rate limit exceeded. Retry after 2 seconds.",
    "param": null
  }
}

`rendering_error`

The PDF was generated but something went wrong during rendering. The response still includes the PDF, but the warnings field flags issues.

{
  "id": "pdf_abc123",
  "object": "pdf",
  "status": "completed_with_warnings",
  "url": "https://files.pdfbase.dev/pdf_abc123.pdf?token=sig_xyz",
  "warnings": [
    {
      "code": "resource_load_failed",
      "message": "Failed to load https://cdn.example.com/logo.png — used fallback.",
      "resource": "https://cdn.example.com/logo.png"
    }
  ]
}

Enable debug: true on the request to get a full screenshot, console log, and failed resource list alongside the PDF. See the Debug Mode guide.

`payment_required`

Your credit balance is 0. Purchase more credits to continue making API calls that consume credits. Read-only operations (GET endpoints) still work.

{
  "error": {
    "type": "payment_required",
    "code": "insufficient_credits",
    "message": "Your credit balance is 0. Purchase more credits at https://app.pdfbase.dev/billing",
    "param": null,
    "credits_remaining": 0
  }
}

Set up auto-refill to prevent service interruptions. PDFBase will automatically purchase credits when your balance drops below your configured threshold.

`idempotency_error`

You reused an idempotency key with different parameters than the original request.

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_conflict",
    "message": "Idempotency key 'order-123-pdf' was already used with different parameters.",
    "param": null
  }
}

`internal_error`

Something went wrong on our end. These are automatically reported and investigated. Retry with exponential backoff.

{
  "error": {
    "type": "internal_error",
    "code": "rendering_crashed",
    "message": "The rendering engine encountered an unexpected error. This has been logged. Please retry.",
    "param": null
  }
}

Retry strategy

For 429 and 5xx errors, retry with exponential backoff:

// The SDK handles this automatically
const pdfbase = new PDFBase({
  apiKey: 'pk_live_xxx',
  maxRetries: 3,        // default: 3
  timeout: 30_000,      // default: 30s
})

Attempt	Delay
1st retry	500ms + jitter
2nd retry	1s + jitter
3rd retry	2s + jitter

The Retry-After header on 429 responses tells you exactly how long to wait. Always respect it.

Billing for errors

You are never charged for failed requests. Only successful PDF generations (status completed or completed_with_warnings) count as credits.

Get Started

Core Concepts

Guides

Integrations

Resources

Error format

HTTP status codes

Error types

`invalid_request`

`authentication_error`

`permission_error`

`not_found`

`rate_limit_error`

`rendering_error`

`payment_required`

`idempotency_error`

`internal_error`

Retry strategy

Billing for errors

​Error format

​HTTP status codes

​Error types

​invalid_request

​authentication_error

​permission_error

​not_found

​rate_limit_error

​rendering_error

​payment_required

​idempotency_error

​internal_error

​Retry strategy

​Billing for errors

Error format

HTTP status codes

Error types

`invalid_request`

`authentication_error`

`permission_error`

`not_found`

`rate_limit_error`

`rendering_error`

`payment_required`

`idempotency_error`

`internal_error`

Retry strategy

Billing for errors