Errors

Every failure returned by the SDK is a *polipage.Error with a Code. SDK-internal codes are lowercase; codes from the API are uppercase.

SDK-internal

Code	When
invalid_options	Constructor options are missing or malformed (`apiKey is required`).
network_error	TCP/TLS-level failure reaching the API (`Network request failed`; the net/http error is the Cause). Retryable.
timeout	The request did not complete within the configured WithTimeout (`Request timed out after <ms>ms`). Retryable.
aborted	Caller context was cancelled, also during the PDF download (`Request was aborted`). Not retryable.
io_failed	Local filesystem write failed in RenderToFile.
DOWNLOAD_FAILED	Fetching a presigned PDF URL failed: `Failed to download PDF: HTTP <status>` with the storage status, or `Failed to download PDF: network error` without one, also when the connection drops while the body is read. Never retryable, whatever the storage status.

Authentication

Code	When
MISSING_API_KEY	No API key in the request.
INVALID_API_KEY	The API key is malformed or revoked.

Billing and lifecycle

Code	When
FORBIDDEN	The key does not have access to the requested resource.
ENVIRONMENT_PROTECTED	The environment is protected: this key may not delete its documents (a service key may).
ORGANIZATION_PAYMENT_GRACE	Organization billing is past due; the organization is read-only.
ORGANIZATION_CANCELLED	The organization has been cancelled.
ORGANIZATION_PURGED	The organization has been purged.
THUMBNAILS_NOT_AVAILABLE	The organization's plan does not include thumbnails.

Not found

Code	When
NOT_FOUND	The requested resource does not exist.
PROJECT_NOT_FOUND	No project matches the supplied slug.
PROJECT_NOT_IN_ENVIRONMENT	The project is not published in the key's environment.
TEMPLATE_NOT_FOUND	No template matches the supplied slug in the published project.
DOCUMENT_NOT_FOUND	No stored document matches the supplied id.
DOCUMENT_GONE	The document was deleted or has expired.

Validation

Code	When
VALIDATION_ERROR	The request body failed validation (unknown field, bad value).
MISSING_DATA	Request body lacks the required Data field.
MISSING_TEMPLATE_SLUG	Template slug is missing.
PROJECT_REQUIRED_FOR_DOCUMENT	RenderInput.Project is empty (`project is required`), checked before any request.
ENVIRONMENT_MISMATCH	The resource belongs to another environment than the key's.
TEMPLATE_ERROR	The template failed to render with the supplied data.
TEMPLATE_UNSAFE	The template, a partial or an SVG asset holds an injection attempt; `detail` names it.
EMPTY_DOCUMENT	The render produced no pages.
RENDER_BODY_TOO_LARGE	The request body exceeds the render size limit.
DOCUMENT_TOO_LARGE	The document exceeds the engine's size or complexity limit.

Rate and quota

Code	When
QUOTA_EXCEEDED	Monthly quota reached (429). Not retryable: it lasts until the monthly reset.
OVERAGE_CAP_EXCEEDED	Overage cap reached (429). Not retryable: it lasts until the monthly reset.
RATE_LIMIT_EXCEEDED	Too many requests. Retryable.

Server

Code	When
INTERNAL_ERROR	The API returned 5xx, or an error answer whose body is not JSON (message `HTTP <status>`, real status kept). Retryable.
PUBLISH_IN_PROGRESS	A publish locks the project in the key's environment. Retryable after Retry-After.
ORGANIZATION_MIGRATING	The organization is being migrated. Retryable.
STORAGE_ACCESS_DENIED	The organization's own storage bucket refuses access (502). Not retryable: restore the bucket role, then call again.
RENDER_TIMEOUT	The render did not finish in time. Retryable.