Skip to content

LearnOperate

Idempotency

Idempotency key

A request is idempotent when sending it twice has the same effect as sending it once; an idempotency key makes a non-idempotent call, like an upload, safe to retry.

In DocSlurpGlossary entry

On this page

An operation is idempotent when doing it twice has the same effect as doing it once. Setting a value is idempotent; adding to it is not. HTTP GET, PUT and DELETE are defined as idempotent. POST, which most APIs use to create things, is not.

That matters when networks fail. Your client uploads growth-plan-2027.pdf and the connection drops before the response arrives. Did the server receive it? If you retry, you may create a second copy and pay to process it twice. If you don’t, you may have lost the upload.

An idempotency key solves this. The client generates a unique value, usually a UUID, and sends it as an Idempotency-Key header with the request. The server stores the key with the response. If the same key arrives again, the server returns the stored response instead of doing the work again.

POST /v1/uploads
Idempotency-Key: 9b2f7c1e-4a0d-4c55-8f0e-2d7b6c3e1a90

Generate the key once per logical operation and reuse it for every retry of that operation. A new key per attempt defeats the purpose.

The gotcha

The key identifies one specific request. Reusing it with a different body is a client bug, and a careful server rejects it rather than replaying a response for a request you didn’t send. In DocSlurp, upload, URL ingest, extract and web ingest routes keep keys for 24 hours, replay with an Idempotency-Replayed: true header, and answer 409 when the payload differs.

Idempotency also applies inside a system: webhook receivers should handle duplicate events, and usage metering should not double-count a retried write.

In DocSlurp

In DocSlurp

Uploads, URL ingests, extracts and web ingests accept an Idempotency-Key header. A repeat within 24 hours replays the stored response with Idempotency-Replayed: true; the same key with a different payload gets 409 (core/server/src/services/idempotency.ts, core/server/src/services/project-intake-actions.ts).

Sources

Jump to