Errors

Every failure thrown by the SDK is a PoliPage\PoliPageException (which extends RuntimeException). The errorCode property tells you what went wrong; the requestId property is what to quote when filing a support ticket. Specialized subclasses under PoliPage\Exception\* let you catch by HTTP status family.

The exception class

use PoliPage\PoliPageException;
use PoliPage\ProjectModeInput;

try {
    $client->render->pdf(new ProjectModeInput(
        project: 'billing',
        template: 'invoice',
        data: ['invoiceNumber' => 'INV-001'],
    ));
} catch (PoliPageException $e) {
    error_log(sprintf('%s %s — %s', $e->errorCode, $e->requestId ?? '', $e->getMessage()));
    throw $e;
}

SDK-internal codes

These originate inside the SDK before any HTTP call (or in response to a network-layer failure). They are lowercase.

Code	When	Recovery
invalid_options	Constructor arguments are missing or malformed (empty apiKey, undiscoverable PSR-18 client).	Fix the call site. Thrown synchronously.
network_error	TCP/TLS-layer failure reaching the API. Surfaced via Exception\ConnectionException.	Automatically retried up to maxRetries times.
timeout	The request did not complete within the configured `timeout`. Surfaced via Exception\TimeoutException.	Automatically retried up to maxRetries times. Raise `timeout` if it keeps tripping.
aborted	A future cancellation primitive aborted the request.	Not retryable. Surface to the caller.

API codes

Returned by the Poli Page API. Uppercase, snake-case. The SDK forwards the code verbatim and raises the matching PoliPage\Exception\* subclass.

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.	Check the constructor was called with `apiKey`.
NOT_FOUND	The `project/template` slug or `documentId` does not exist.	Verify the slug/id; check the template is published in this environment.
VALIDATION_ERROR	The `data` array 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`s 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.

Example

<?php

require __DIR__ . '/vendor/autoload.php';

use PoliPage\Exception\RateLimitException;
use PoliPage\PoliPage;
use PoliPage\PoliPageException;
use PoliPage\ProjectModeInput;

$client = PoliPage::client($_ENV['POLI_PAGE_API_KEY']);

try {
    $pdf = $client->render->pdf(new ProjectModeInput(
        project: 'billing',
        template: 'invoice',
        data: ['invoiceNumber' => 'INV-001'],
    ));
} catch (RateLimitException $e) {
    // Custom strategy on top of the SDK's built-in retries.
    sleep(30);
    throw $e;
} catch (PoliPageException $e) {
    throw $e;
}

See also

• Retries and idempotency
• Observability