Retries and idempotency

The Poli Page SDK retries transient failures automatically. Render operations carry an auto-generated UUID v4 idempotency key, so retries do not produce duplicate stored documents on the server.

Default retry policy

• network_error, timeout, 5xx responses, and 429 (QUOTA_EXCEEDED) are retried.
• Up to maxRetries attempts (default 2 — three total attempts).
• Exponential backoff starting at retryDelay ms (default 500), doubling each attempt.
• Honors the Retry-After response header when present.
• aborted (caller-cancelled) is never retried.

Disabling retries

Set maxRetries: 0 on the constructor to disable retries entirely.

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

Idempotency

Every render request includes a UUID v4 Idempotency-Key header generated by the SDK. The API treats requests with the same key as the same operation, so retries from inside the SDK never create duplicate stored documents.

If you orchestrate your own retries on top of the SDK (not recommended), supply your own deterministic key via idempotencyKey on the input:

const pdf = await client.render.pdf({
  project: 'billing',
  template: 'invoice',
  data: { invoiceNumber: 'INV-001' },
  idempotencyKey: 'invoice-INV-001-v1',
});

Same input + same key → same stored document. Different key with same data → new document.

Example

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

const client = new PoliPage({
  apiKey: process.env.POLI_PAGE_API_KEY!,
  maxRetries: 4,
  retryDelay: 250,
});

const pdf = await client.render.pdf({
  project: 'billing',
  template: 'invoice',
  data: { invoiceNumber: 'INV-001' },
});

See also

• Errors
• Configuration