Retries and idempotency

The Poli Page PHP 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 seconds (default 0.5), 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.

$client = new PoliPage(
    apiKey: $_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 the input’s idempotencyKey parameter:

use PoliPage\ProjectModeInput;

$pdf = $client->render->pdf(new ProjectModeInput(
    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

<?php

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

use PoliPage\PoliPage;
use PoliPage\ProjectModeInput;

$client = new PoliPage(
    apiKey: $_ENV['POLI_PAGE_API_KEY'],
    maxRetries: 4,
    retryDelay: 0.25,
);

$pdf = $client->render->pdf(new ProjectModeInput(
    project: 'billing',
    template: 'invoice',
    data: ['invoiceNumber' => 'INV-001', 'total' => 1280],
));

See also

• Errors
• Configuration