Retries and idempotency

The Poli Page Python SDK retries transient failures automatically. Render operations carry an auto-generated UUID4 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 max_retries attempts (default 2 — three total attempts).
• Exponential backoff starting at retry_delay seconds (default 0.5), doubling each attempt, with [0.5, 1.5) jitter.
• Honors Retry-After and Retry-After-Ms (sub-second precision wins), capped at 30 seconds.
• Caller cancellation (asyncio.CancelledError, KeyboardInterrupt) is never retried.

Disabling retries

Set max_retries=0 on the constructor to disable retries entirely.

from poli_page import PoliPage

client = PoliPage(max_retries=0)

Idempotency

Every POST request includes a UUID4 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 idempotency_key on the input:

pdf = client.render.pdf({
    "project": "billing",
    "template": "invoice",
    "data": {"invoiceNumber": "INV-001", "total": 1280},
    "idempotency_key": "invoice-INV-001-v1",
})

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

Example

from poli_page import PoliPage

client = PoliPage(max_retries=4, retry_delay=0.25)

pdf = client.render.pdf({
    "project": "billing",
    "template": "invoice",
    "data": {"invoiceNumber": "INV-001", "total": 1280},
})

See also

• Errors
• Configuration