Idempotency

​

Overview

​

Usage

curl -X POST https://api.pdfbase.dev/v1/pdfs \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Idempotency-Key: order-42-invoice" \
  -d '{
    "html": "<h1>Invoice for Order #42</h1>",
    "output": "url"
  }'

​

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:

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_conflict",
    "message": "Idempotency key 'order-42-invoice' was already used with different parameters.",
    "param": null
  }
}

4. Keys work on all POST endpoints — PDF creation, template creation, batch creation, merge, split, etc.
5. GET, PATCH, DELETE are inherently idempotent. You don’t need keys for those.

​

Key naming patterns

​

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.