Errors

Every failure thrown by the SDK is an instance of PoliPageError. The code field tells you what went wrong; the requestId field is what to quote when filing a support ticket.

The error class

import { PoliPageError } from '@poli-page/sdk';

try {
  await client.render.pdf({ project: 'billing', template: 'invoice', data: {} });
} catch (err) {
  if (err instanceof PoliPageError) {
    console.error(err.code, err.requestId, err.message);
  } else {
    throw err;
  }
}

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	The options passed to the PoliPage constructor are invalid (missing apiKey, malformed baseUrl, etc.).	Fix the constructor call. Thrown synchronously.
network_error	TCP/TLS-layer failure reaching the API.	Automatically retried up to maxRetries times.
timeout	The request did not complete within the configured `timeout`.	Automatically retried up to maxRetries times. Raise `timeout` if it keeps tripping.
aborted	The caller-supplied `signal` 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.

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` object 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

import { PoliPage, PoliPageError } from '@poli-page/sdk';

const client = new PoliPage({ apiKey: process.env.POLI_PAGE_API_KEY! });

try {
  const pdf = await client.render.pdf({
    project: 'billing',
    template: 'invoice',
    data: { invoiceNumber: 'INV-001' },
  });
  // ...
} catch (err) {
  if (err instanceof PoliPageError && err.code === 'QUOTA_EXCEEDED') {
    // Custom strategy beyond the SDK's built-in retries.
    return;
  }
  throw err;
}

See also

• Retries and idempotency
• Observability