Errors

Every failure raised by the SDK is a PoliPage::Error subclass. Catch a specific subclass when you want narrow control (rescue PoliPage::RateLimitError), or rescue PoliPage::Error to handle every SDK failure at once. The code: reader is the machine-readable string; request_id: is what to quote on a support ticket.

The error hierarchy

require "poli_page"

client = PoliPage::Client.new(api_key: ENV.fetch("POLI_PAGE_API_KEY"))

begin
  client.render.pdf(project: "billing", template: "invoice", data: {})
rescue PoliPage::Error => e
  warn "#{e.class}: #{e.code} (request_id=#{e.request_id})"
end

HTTP status maps to a subclass via PoliPage::Internal::HTTP.classify:

• 400 → ValidationError
• 401 → AuthenticationError
• 403 → PermissionDeniedError
• 404 → NotFoundError
• 410 → GoneError
• 429 → RateLimitError
• other 4xx / 5xx → APIError

The SDK-internal subclasses (InvalidOptionsError, ConnectionError, TimeoutError, DownloadError, InternalError) are raised before any HTTP call or in response to a network-layer failure.

API codes

Returned by the Poli Page API. Uppercase, snake-case. The SDK forwards the code verbatim into Error#code.

Code	When	Recovery
INVALID_API_KEY	The API key is malformed or revoked.	Rotate the key in the dashboard.
MISSING_API_KEY	No API key was provided in the request.	Pass `api_key:` to the constructor.
NOT_FOUND	The `project/template` slug or `document_id` does not exist.	Verify the slug or id; check the template is published in this environment.
VALIDATION_ERROR	The `data:` hash does not satisfy the template schema.	Inspect the template schema in the dashboard.
MISSING_DATA	The request body lacks a required `data` field.	Pass `data: {}` (or with values) on every render call.
QUOTA_EXCEEDED	You exceeded the per-key rate limit or monthly quota.	Automatically retried; bump tier for sustained higher throughput.
PAYMENT_REQUIRED	The organization billing is past due.	Update the payment method in the dashboard.
INTERNAL_ERROR	The API returned 5xx.	Automatically retried; contact support if it persists.

The full list of API codes lives in the reference.

Predicate helpers

PoliPage::Error exposes #auth_error?, #rate_limit_error?, #validation_error?, #network_error?, and #retryable? for callers who want a single rescue clause backed by introspection.

Example

require "poli_page"

client = PoliPage::Client.new(api_key: ENV.fetch("POLI_PAGE_API_KEY"))

begin
  pdf = client.render.pdf(
    project:  "billing",
    template: "invoice",
    data:     { invoice_number: "INV-001" }
  )
rescue PoliPage::RateLimitError => e
  # Custom strategy beyond the SDK's built-in retries.
  warn "rate limited (request_id=#{e.request_id}); backing off"
rescue PoliPage::Error => e
  warn "render failed: #{e.code} (#{e.class})"
  raise
end

See also

• Retries and idempotency
• Observability