Skip to main content

​
Overview

Network failures happen. When a request times out, you don’t know if PDFBase processed it or not. Idempotency keys let you safely retry without creating duplicate PDFs or double-processing batch jobs. Pass an Idempotency-Key header with any POST request. If PDFBase has already processed a request with that key, it returns the original response instead of creating a new resource.

​
Usage

The first request creates the PDF. Retrying with the same key returns the exact same response — same id, same url, no additional credit charged.

​
Rules

  1. Keys are scoped to your account. Two different accounts can use the same key string without conflict.
  2. Keys expire after 24 hours. After that, the same key can be reused for a new request.
  3. Keys are tied to parameters. Reusing a key with different request parameters returns a 409 Conflict:
  1. Keys work on all POST endpoints — PDF creation, template creation, batch creation, merge, split, etc.
  2. GET, PATCH, DELETE are inherently idempotent. You don’t need keys for those.

​
Key naming patterns

Use keys that map to your business logic:
Don’t use random UUIDs as idempotency keys — they defeat the purpose. Use deterministic keys derived from your business entities so retries naturally deduplicate.

​
How it works internally

  1. PDFBase hashes the idempotency key + your account ID.
  2. On first request: stores the hash → request parameters → response.
  3. On retry: compares stored parameters to new parameters. If they match, returns the stored response. If they don’t, returns 409.
  4. The stored response is returned even if the original PDF file has expired — the response metadata (ID, pages, bytes) is preserved, but the url may be regenerated.