> ## Documentation Index
> Fetch the complete documentation index at: https://pdfbase.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Safely retry requests without creating duplicate resources.

## 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

```bash theme={null}
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"
  }'
```

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`:

```json theme={null}
{
  "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

Use keys that map to your business logic:

| Use case          | Key pattern                   | Example                 |
| ----------------- | ----------------------------- | ----------------------- |
| Invoice per order | `order-{id}-invoice`          | `order-42-invoice`      |
| Monthly report    | `report-{year}-{month}`       | `report-2026-05`        |
| Batch per import  | `import-{batch_id}`           | `import-csv-20260519`   |
| Template update   | `tpl-update-{name}-{version}` | `tpl-update-invoice-v3` |

<Tip>
  Don't use random UUIDs as idempotency keys — they defeat the purpose. Use deterministic keys derived from your business entities so retries naturally deduplicate.
</Tip>

## 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.