Errors

Every failure raised by the SDK is an instance of PoliPage::Error (a StandardError subclass). Catch a specific subclass when you want narrow handling, or rescue PoliPage::Error to handle every SDK failure at once. The error’s #code reader is the machine-readable string returned by the API.

SDK-internal classes

Raised before any HTTP call, or in response to a network-layer failure.

Code	When
`PoliPage::InvalidOptionsError`	Constructor or method options are missing or malformed. Raised before any HTTP call. Not retryable.
`PoliPage::ConnectionError`	TCP/TLS-layer failure reaching the API. Retryable.
`PoliPage::TimeoutError`	The request did not complete within the configured `timeout:`. Retryable.
`PoliPage::DownloadError`	Failure on the unauthenticated presigned-URL second-hop fetch. Not retried by the SDK.
`PoliPage::InternalError`	Unexpected response shape from the API (e.g., non-JSON body).

API error classes (by HTTP status)

The transport classifies API responses into one of these subclasses based on HTTP status. The #code reader carries the machine-readable string from the response body.

Code	When
`PoliPage::ValidationError`	HTTP 400 — request body or parameters rejected by the API.
`PoliPage::AuthenticationError`	HTTP 401 — missing or invalid API key.
`PoliPage::PermissionDeniedError`	HTTP 403 — key lacks permission for the requested resource.
`PoliPage::NotFoundError`	HTTP 404 — project/template slug or document id does not exist.
`PoliPage::GoneError`	HTTP 410 — resource existed but was deleted.
`PoliPage::RateLimitError`	HTTP 429 — per-key rate limit or monthly quota reached. Retryable.
`PoliPage::APIError`	Any other 4xx / 5xx the SDK does not map to a more specific class.

Authentication codes

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

Billing and lifecycle codes

Code	When
`PAYMENT_REQUIRED`	Organization billing is past due.
`FORBIDDEN`	The key does not have access to the requested resource.
`ORGANIZATION_CANCELLED`	The organization has been cancelled.
`ORGANIZATION_PURGED`	The organization has been purged.

Not-found codes

Code	When
`NOT_FOUND`	The project/template slug does not exist or is not published.
`VERSION_NOT_FOUND`	The pinned version does not exist for this template.
`DOCUMENT_NOT_FOUND`	No stored document matches the supplied id.
`GONE`	The resource existed but has been deleted.

Validation codes

Code	When
`VALIDATION_ERROR`	`data` does not satisfy the template schema.
`MISSING_DATA`	Request body lacks the required `data` field.
`MISSING_PROJECT_OR_TEMPLATE`	Project mode call without both `project` and `template`.
`MISSING_TEMPLATE_SLUG`	Template slug is missing.
`PROJECT_REQUIRED_FOR_DOCUMENT`	render.document was called without `project:`.
`INVALID_VERSION_FORMAT`	The `version` string is not a valid semver.
`VERSION_REQUIRED`	Live keys require a pinned `version`.
`INVALID_VERSION_FOR_KEY_ENV`	Sandbox key targeting a live-only version, or vice versa.

Rate and quota codes

Code	When
`QUOTA_EXCEEDED`	Per-key rate limit or monthly quota reached. Retryable.
`OVERAGE_CAP_EXCEEDED`	Hard overage cap reached. Not retryable.

Server codes

Code	When
`INTERNAL_ERROR`	The API returned 5xx. Retryable.