Errors

Every error response is RFC 9457 application/problem+json:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No such template",
  "error_code": "TEMPLATE_NOT_FOUND",
  "request_id": "eb0315c5-14ad-4250-a8aa-2c7bb41fa26d"
}

Program against two fields:

• error_code: stable and machine-readable. Branch on it, not on detail (human wording may improve over time) and not on the HTTP status alone (one status can carry several codes).
• request_id: quote it when contacting support; it identifies the exact request.

Error codes are an open set: new codes may be added. Handle unknown codes by falling back on the HTTP status class.

Handling by class

Class	Meaning	Handling
400	The request is malformed	Fix the request; do not retry unchanged
401 / 403	Key missing, not set up, or lacking scope	Check the key and its scopes in the Console
404	Resource doesn't exist (or its record expired)	Check ids; note output expiry
409	Conflict with current state	Resolve the conflict (publish a version, change the idempotency key, …)
422	The request is well-formed but can't be processed	Fix the data or content; the code says exactly what
429	Throttled	Back off and retry with an idempotency key
5xx	Server-side failure	Retry with backoff and an idempotency key

Error code registry

400: malformed requests

Code	Meaning
INVALID_JSON	The body is not parseable JSON
INVALID_REQUEST	The body fails validation (the detail says where)
UNKNOWN_FIELD	The body contains a field the API doesn't recognize
INVALID_CURSOR	The pagination cursor is malformed
INVALID_IDEMPOTENCY_KEY	The Idempotency-Key header is malformed
INVALID_STATUS_FILTER	An unsupported status query value
INVALID_VERSION	The version value is not a valid version number
INVALID_RESPONSE_MODE	response.mode is not binary or json
UNSUPPORTED_FILE_FORMAT	file_format is not supported
INVALID_ACTOR	The X-On-Behalf-Of value is malformed

401 / 403: authentication and authorization

Code	Meaning
MISSING_API_KEY	No x-api-key header
KEY_NOT_PROVISIONED	The key is not set up for this API: check the Console APIs page
INSUFFICIENT_SCOPE	The key lacks the scope this operation requires

404 / 405: missing resources

Code	Meaning
ROUTE_NOT_FOUND	No such endpoint
TEMPLATE_NOT_FOUND / VERSION_NOT_FOUND / ASSET_NOT_FOUND / JOB_NOT_FOUND	No such resource in your account
OUTPUT_NOT_FOUND	The output's retention window (~20 h) has passed
METHOD_NOT_ALLOWED	The endpoint exists but not for this HTTP method

409: conflicts

Code	Meaning
CONCURRENT_MODIFICATION	Another request changed the resource first; re-read and retry
IDEMPOTENCY_KEY_REUSED	Same key, different body
TEMPLATE_ARCHIVED	The template is archived and cannot generate
NO_PUBLISHED_VERSION	Nothing is published; publish or pin a version
NOTHING_TO_COPY	The copy source has no finalized version
UPLOAD_NOT_FOUND	Finalize was called but no base PDF was uploaded
VERSION_NOT_FINALIZED	The version is still awaiting its base PDF

413 / 422: content that can't be processed

Code	Meaning
HTML_TOO_LARGE	HTML content exceeds 1 MB
MISSING_ACTOR	A write without X-On-Behalf-Of
UNSUPPORTED_FIELD_TYPE	A field type the API doesn't support
MISSING_MERGE_TAGS / INVALID_MERGE_VALUES / UNKNOWN_MERGE_TAGS	Strict data validation failed
INVALID_PDF / BASE_PDF_TOO_LARGE / TOO_MANY_PAGES	The base PDF can't be used (finalize)
ASSET_TOO_LARGE / INVALID_IMAGE	The asset upload is over 2 MB or not a valid PNG/JPEG
GENERATION_WARNINGS	Warnings occurred and the request set on_warning: "error"
BATCH_ITEMS_INVALID	One or more batch items failed validation; per-item errors included
TABLE_OVERFLOW	Table rows overflow the box and the field sets overflow: "error"
FILL_REQUIRES_TEMPLATE	A fill field on a template-free document
RENDER_FAILED	The document could not be rendered from the given content
HTML_RENDER_FAILED / HTML_RENDER_TIMEOUT / HTML_TOO_MANY_PAGES	The HTML document failed to render, took too long, or paginated past the page limit
HTML_REQUIRES_JSON_RESPONSE	HTML documents require response.mode: "json"
HTML_TAGGED_CONFLICT	tagged: true combined with fields/options/typography/flatten/unicode

5xx: server-side

Code	Meaning
INTERNAL_ERROR	Unexpected failure; retry with backoff, then contact support with the request_id
SERVICE_UNCONFIGURED	The service cannot serve this request; contact support

Errors vs. warnings

Errors fail the request; warnings never do. A value that can't be rendered (an unencodable glyph, a missing asset) is skipped and reported instead. See Warnings for that model and its registry, and on_warning to turn warnings into 422 GENERATION_WARNINGS when your workflow demands all-or-nothing.