How Do I Make PDF API Retries Safe with Idempotency Keys?

Design for the response that never arrived

Make PDF API retries safe by sending a unique idempotency key with every job-creation request. The server stores that key with a fingerprint of the request and returns the original result when the same request is retried.

Without this, a timeout can create two parse jobs, two charges, two artifacts, and two completion events.

POST /v1/parse HTTP/1.1
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: candidate-applied-2026-07-06-001
Content-Type: multipart/form-data

The key identifies the business operation, not the TCP connection or one upload attempt.

The timeout problem

A client uploads a PDF. The server accepts it, but the response is lost. The client cannot tell whether the job exists, so it retries.

The second request is not malicious. It is normal network behavior. The API must make it safe.

Create a key per business operation

Generate a random key or derive one from a stable event ID in your system. Reuse it only when retrying that exact request.

The DocuShell API accepts idempotency keys for queued workflows described in the API Hub. A useful server record binds the key to the authenticated account, endpoint, request fingerprint, job ID, and original response.

Handle in-flight duplicates

Two identical requests can arrive almost together. Reserve the key before expensive work begins. If another request arrives while the first is still being created, return a clear in-progress response rather than starting a second job.

Once the job exists, later retries should receive the same job identity.

Reject key misuse

If a client reuses the key with a different file or options, return a conflict. Silently treating it as the old request hides a bug; treating it as new defeats idempotency.

Compare a stable request fingerprint rather than storing the entire sensitive document in the idempotency table.

Make downstream steps idempotent too

Job creation is only the start. Webhook receivers, database writes, and artifact imports should deduplicate by job or event ID.

Reliable document automation assumes retries will happen. Idempotency turns them from an incident into an ordinary code path.

What belongs in the request fingerprint

Bind the key to the authenticated account, endpoint, file identity, and processing options that change the result. A content hash can identify the file without storing its bytes in the idempotency record.

Be careful with multipart requests and metadata ordering. Normalize the fields before hashing so equivalent requests produce the same fingerprint.

Replay the original response

When the first request succeeds, store the status code, job ID, and stable response body. A retry should receive that original operation identity, not a newly generated job with a note saying it might be a duplicate.

If the original request failed validation before any operation was created, document whether the key may be reused after correction. Consistency matters more than one universal policy.

Idempotency is not deduplication by file hash. The same PDF may be intentionally processed twice with different options; the same business operation should not be created twice because a response was lost.

Expiry and storage failure

Choose an idempotency retention period long enough to cover client retries and the job lifecycle. Expiring keys too early can recreate old work. Keeping them forever creates unnecessary state.

For paid or high-impact operations, fail closed when the idempotency store is unavailable. Starting work without duplicate protection may be worse than returning a temporary error.

Test concurrency, not only sequential retries

Send the same key from several clients at once. Confirm that one operation is created and every response resolves to it. Then reuse the key with a changed file and verify that the API returns a conflict.

Pair idempotent creation with an async PDF job contract, deduplicated webhooks, and secure artifact delivery. The broader document webhook automation guide covers retry-safe consumers.