Errors

Every failure raised by the SDK is an instance of PoliPageError with a code. SDK-internal codes are lowercase; codes from the API are uppercase.

SDK-internal

Code	When
invalid_options	Constructor arguments are missing or malformed (`apiKey is required`).
network_error	TCP/TLS-level failure reaching the API (`Network request failed`; the httpx exception is the `__cause__`). Retryable.
timeout	The request did not complete within `timeout` (`Request timed out after <ms>ms`). Retryable.
DOWNLOAD_FAILED	The S3 second-hop download failed: `Failed to download PDF: HTTP <status>` with the storage `status`, or `Failed to download PDF: network error` without one. 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.

Organization state and permission

Code	When
ORGANIZATION_PAYMENT_GRACE	The organization has unpaid invoices: it is read-only and writes are refused.
ORGANIZATION_CANCELLED	The organization has been cancelled: read-only until purge.
ORGANIZATION_PURGED	The organization has been purged (410).
ORGANIZATION_MIGRATING	The organization's storage is being migrated (503). Retryable.
FORBIDDEN	The document belongs to another organization or another environment than the key's.
ENVIRONMENT_PROTECTED	documents.delete in a protected environment by a key whose role is not owner or admin.
THUMBNAILS_NOT_AVAILABLE	documents.thumbnails on the Free tier.

Not found

Code	When
NOT_FOUND	Generic not found, for example a removed route.
PROJECT_NOT_FOUND	No project with this slug in the organization.
PROJECT_NOT_IN_ENVIRONMENT	The project was never published in the key's environment, or was removed from it.
TEMPLATE_NOT_FOUND	The template is not in the project's copy published in the key's environment.
DOCUMENT_NOT_FOUND	No stored document matches the supplied id.
DOCUMENT_GONE	The document was deleted, or is a sandbox document older than 30 days (410).

Validation

Code	When
VALIDATION_ERROR	The request body failed validation, for example thumbnail options out of bounds.
MISSING_DATA	Request body lacks the required `data` field.
MISSING_TEMPLATE_SLUG	Template slug is missing.
PROJECT_REQUIRED_FOR_DOCUMENT	Input without a `project` on a render method. Rejected locally before any HTTP call.
TEMPLATE_ERROR	The engine rejected the template or its data.
TEMPLATE_UNSAFE	The template, a partial or an SVG asset holds an injection attempt; `detail` names it.
EMPTY_DOCUMENT	The render produced zero pages.
ENVIRONMENT_MISMATCH	A caller named another environment than the key's. This SDK never sends one.
RENDER_BODY_TOO_LARGE	The request body is over the API's size limit (413).
DOCUMENT_TOO_LARGE	The document exceeds an engine cap (413).

Rate and quota

Code	When
RATE_LIMIT_EXCEEDED	Per-key render rate limit reached. Retryable.
QUOTA_EXCEEDED	Monthly quota reached. Not retryable: it lasts until the monthly reset.
OVERAGE_CAP_EXCEEDED	Overage cap reached (paid tiers). Not retryable: it lasts until the monthly reset.

Server

Code	When
INTERNAL_ERROR	Unexpected server error, or an error answer whose body is not JSON (message `HTTP <status>`, real status kept). Retryable.
STORAGE_ACCESS_DENIED	The organization's own storage bucket refuses access (502). Not retryable: restore the bucket role, then call again.
PUBLISH_IN_PROGRESS	The project is being published into this environment (503 with `Retry-After`). Retryable.
RENDER_TIMEOUT	The engine's time budget expired (504). Retryable.