Idempotency-Key: Safe Retries for PDF Jobs
Send Idempotency-Key on jobs under /api/v1/. Successful responses cache 24 hours in process memory; replays return Idempotency-Replayed: true, not a second run.

Network timeouts and client retries are normal for multipart PDF uploads. Without an idempotency key, a second POST runs the same merge, OCR, or compress again from scratch, duplicating the upload and the processing time. With Idempotency-Key, PDF123 can replay the first successful response instead.
What the middleware does
The server middleware in pdfx-server applies only to mutating calls: POST to paths under /api/v1/ (including /api/v1/pipeline). GET and other methods pass through unchanged. If the request has no Idempotency-Key header (or it is blank after trim), the op runs normally with no cache lookup.
When the header is present:
- The store keys the entry by principal + key. The principal is derived from
X-API-KEY(askey:…), elseAuthorization(asauth:…), else the literalanon. Those two values are hashed (SHA-256) into the map key; the request body is not part of the key. - On a cache hit within 24 hours, the middleware returns the stored status, content type, content disposition, and body, and sets
Idempotency-Replayed: true. - On a miss, the request proceeds. Only successful responses are buffered and stored (non-success responses are not cached for replay).
- Response bodies are buffered up to 100 MiB so a replay can resend the file bytes. A body that cannot be buffered does not silently skip the cache: that request returns HTTP 500, so a response over the limit fails rather than passing through uncached.
Failed jobs are safe to retry with the same key: because failures are not stored, the next attempt can succeed and then become the cached result. Do not reuse a key for a different file or parameters; the cache does not hash the body, only principal and key. Two callers that share neither API key nor Authorization cannot collide by accident—anonymous callers share the anon principal, so they must pick distinct keys.
How to send it
Pick a stable opaque string per logical job (UUID is fine):
curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-F "[email protected]"
Anonymous and API-key callers both work. Pipelines that chain watermark then compress should still send one key per HTTP request you want to dedupe—including each step if you POST them separately, or one key for a single /api/v1/pipeline call.
Browser one-offs on tool pages (Compress, OCR, …) do not require you to invent a key; the header matters for clients that retry. The published skill at /skills/pdf123.md shows an Idempotency-Key on a pipeline example for the same reason.
Client patterns that work
- Generate the key before the first POST; reuse it on timeout retries for that same logical job.
- On success, check for
Idempotency-Replayed: trueif you need to know whether this response came from cache or ran the op again. - Change the key when the file, op, or parameters change—even if the principal stays the same.
- For
/api/v1/pipeline, one key covers the whole pipeline POST, not each inner step.
What replay is not
Replay is not a durable job queue. The store is process-local (HashMap behind a mutex) with a 24-hour TTL. After expiry, or after a process restart that drops the in-memory map, the same key runs the op again. Multi-instance deployments do not share that map unless you put a shared store in front—today’s middleware is per process.
Treat Idempotency-Replayed: true as proof this response came from cache, not as a permanent ledger. It does not mean the PDF was re-processed, and it does not extend the TTL.
More surface detail: Developers and Built for AI agents. Tool pages such as Compress remain available for one-off browser jobs without inventing keys.