Glossary

Idempotency key

The fix for the one question a dropped connection leaves you: did that request go through?

By Roger Campos · Last updated: September 2026

TL;DR

An idempotency key is a unique string a client sends with a request, usually in an Idempotency-Key header, so the server can recognise a retry of the same request. Instead of doing the work — and the billing — a second time, the server returns the result of the first attempt.

Start free See the API

Free plan, no credit card. 1,000 credits a month.

How it works

The problem it solves

You send a request and the connection drops before the response arrives. Did the server receive it? You cannot tell. Retrying risks doing it twice — two charges, two emails, two jobs. Not retrying risks doing it zero times.

An idempotency key removes the guess. The client generates a unique value — a UUID — for each logical request and sends it with every attempt. The server stores the key with the first request's outcome; a later request with the same key gets that outcome back. Stripe popularised the pattern, and the IETF has a draft standard for the Idempotency-Key header.

A key identifies a request, not its content: reusing it for a different request is an error, not a cache lookup.

URLpipe

How URLpipe uses it

Send an Idempotency-Key header of up to 255 printable ASCII characters. Within 24 hours, the same key returns the first request's token and result — one charge, one webhook — and the replay carries Idempotent-Replayed: true. Keys belong to the project. A key reused for a different request is refused with a 422 and nothing runs. Over MCP, pass it as the idempotency_key argument.

A request that is safe to retry

curl -X POST https://urlpipe.dev/markdown \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c2e9a-3b1d-4c7e-9a8f-2d6b1e4c0a77" \
  -d '{"url": "https://example.com"}'

Duplicates are handled without a key too: an identical request that arrives while the first is still running waits for it and is answered free. The key covers the case that one cannot — a retry after the first has finished. See Retries & duplicates.

Try it

Idempotency key, on a page you choose

Turn any URL into clean Markdown

Paste a link and get the page's main content as tidy Markdown — headings, lists, links and code kept, navigation and cookie banners stripped. The format LLMs and RAG pipelines work best with.

Try it free

FAQ

Frequently asked questions

What should I use as an idempotency key?

A random UUID generated once per logical operation and reused on every retry of it. Don't derive it from the time of the attempt.

Is an idempotency key the same as caching?

No. A cache decides whether a stored result is fresh enough to reuse; a key decides whether this is a request you already sent. A retry with a key returns the first result even if you asked for a fresh fetch.

Which HTTP methods need an idempotency key?

POST, mainly. GET, PUT and DELETE are defined as idempotent already; POST is not, and it is what most APIs use to start work.

Keep reading

Fetch a page from a residential address Rendered HTML API Idempotency keys explained Hydration Sign in with Google or GitHub Verify a webhook signature in Java All of glossary

See it on your own pages.

Free plan, no card. Confirm your email and your API key is live — you'll be making real requests in minutes.

Start free Email the team