Retries and idempotency

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

Default retry policy

• ConnectionError, TimeoutError, 5xx responses, and 429 (RateLimitError) 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.
• Honors the Retry-After response header when present.
• InvalidOptionsError and caller-cancelled exceptions are never retried.

Disabling retries

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

client = PoliPage::Client.new(
  api_key:     ENV.fetch("POLI_PAGE_API_KEY"),
  max_retries: 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 internal retries 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 idempotency_key: keyword on the render call:

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

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

Example

require "poli_page"

client = PoliPage::Client.new(
  api_key:     ENV.fetch("POLI_PAGE_API_KEY"),
  max_retries: 4,
  retry_delay: 0.25
)

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

See also

• Errors
• Configuration