Errors & warnings

How to read Paperbase errors and warnings, and how to act on them programmatically.

Paperbase uses two distinct mechanisms to tell you about problems: errors (HTTP 4xx/5xx) and warnings (a field on a 200 response). Understanding the difference is important — a successful render can still have actionable warnings.

Errors vs warnings

	Errors	Warnings
HTTP status	4xx or 5xx	200
PDF produced?	No	Yes
Location	Top-level `error` object	`warnings[]` array
Action	Fix before retrying	Optionally improve

A warning means Paperbase rendered the PDF but detected something sub-optimal (a font fell back, a logo was low-resolution, a table header won't repeat on page breaks). The PDF is usable; the warning tells you how to make it better.

An error means rendering was not attempted or failed completely. No PDF is returned.

Error response shape

Every error response is a JSON object with an error key:

{
  "error": {
    "code": "PB_INVALID_API_KEY",
    "type": "authentication_error",
    "human_message": "The API key provided is invalid or expired.",
    "agent_message": "Obtain a valid API key from https://paperbase.dev/dashboard or call POST /v1/keys/test for a free 24-hour test key.",
    "docs_url": "https://paperbase.dev/docs/errors/PB_INVALID_API_KEY",
    "retryable": false,
    "request_id": "req_01HZXYZ"
  }
}

Field	Type	Description
`code`	`string`	Machine-readable error code
`type`	`string`	Error category
`human_message`	`string`	End-user-safe message
`agent_message`	`string`	Machine-readable fix instruction for AI agents
`docs_url`	`string`	Link to this docs page
`retryable`	`boolean`	Whether you should retry without changing the request
`request_id`	`string`	Use this when contacting support

Error codes

Code	HTTP	Type	Retryable	Description
`PB_INVALID_API_KEY`	401	`authentication_error`	No	Missing, malformed, or expired API key
`PB_MONTHLY_QUOTA_EXCEEDED`	429	`rate_limit_error`	No	Workspace has used all renders for this month
`PB_RATE_LIMIT_EXCEEDED`	429	`rate_limit_error`	Yes	Too many requests per minute — check `Retry-After` header
`PB_INPUT_TOO_LARGE`	413	`invalid_request_error`	No	Input exceeds 5 MB
`PB_TOO_MANY_ASSETS`	422	`invalid_request_error`	No	More than 200 external asset URLs in input
`PB_RENDER_TIMEOUT`	504	`render_error`	Yes	Render exceeded 25-second timeout
`PB_INVALID_REQUEST`	400	`invalid_request_error`	No	Malformed request body
`PB_UNKNOWN_ERROR`	500	`api_error`	Yes	Internal error — retry once after 1 second

Handling errors in the SDK

import { Paperbase, PaperbaseError } from "paperbase";
 
const paperbase = new Paperbase({ apiKey: process.env.PAPERBASE_API_KEY! });
 
try {
  const result = await paperbase.pdf.generate({ ... });
} catch (err) {
  if (err instanceof PaperbaseError) {
    console.error(err.code);         // "PB_MONTHLY_QUOTA_EXCEEDED"
    console.error(err.agentMessage); // fix instruction
    console.error(err.retryable);    // false
  }
}

Handling errors with raw fetch

const res = await fetch("https://api.paperbase.dev/v1/pdf/generate", { ... });
 
if (!res.ok) {
  const { error } = await res.json();
  console.error(error.code, error.agent_message);
}

Warning response shape

Warnings appear in the warnings array on a 200 response. An empty array means no warnings.

{
  "job_id": "job_01HZXYZ",
  "url": "https://storage.paperbase.dev/…",
  "warnings": [
    {
      "code": "PB_FONT_FALLBACK",
      "severity": "warning",
      "human_message": "Font 'Lato' is not available. Fell back to Inter.",
      "agent_message": "The requested font is not in Paperbase's font cache. Use one of the supported font names: Inter, Playfair Display, Source Code Pro, JetBrains Mono.",
      "suggested_fix": "Change theme.body_font to 'Inter' or remove the field to use the default.",
      "docs_url": "https://paperbase.dev/docs/warnings/PB_FONT_FALLBACK",
      "agent_repairable": true,
      "location": { "selector": "body" }
    }
  ]
}

Field	Type	Description
`code`	`WarningCode`	Machine-readable warning identifier
`severity`	`"warning" \| "info"`	`warning` is more impactful; `info` is informational
`human_message`	`string`	Plain-English description for end users
`agent_message`	`string`	Detailed instruction for AI agents
`suggested_fix`	`string`	Specific change to make to the request
`docs_url`	`string`	Link to the warning's catalog page
`agent_repairable`	`boolean`	`true` if an AI agent can fix this without human help
`location`	`object?`	Optional `page`, `selector`, and/or `url` pointing at the problem
`score_degrading`	`boolean?`	`true` if this warning reduces the design quality score

Acting on `suggested_fix` programmatically

If you're building an AI agent that calls Paperbase, use agent_repairable and suggested_fix to drive self-correction:

const result = await paperbase.pdf.generate(request);
 
const repairableWarnings = result.warnings.filter(w => w.agent_repairable);
 
if (repairableWarnings.length > 0) {
  // Pass warnings back to the LLM with the original request
  const fixes = repairableWarnings.map(w => w.suggested_fix).join("\n");
  // ... apply fixes to request, retry once
}

For non-repairable warnings (agent_repairable: false), surface human_message to the end user — these require manual intervention (e.g. upgrading assets, restructuring content).

Warning catalog

All 12 warning codes are documented individually:

On this page