> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://apidocs.polytomic.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://apidocs.polytomic.com/_mcp/server.

This guide explains how to use idempotency keys with the Polytomic API.

Idempotent requests let you safely retry a call without causing duplicate
side effects. Running the same operation more than once produces the same
result as running it exactly once.

## Idempotency keys

You mark a request as idempotent by setting the `Idempotency-Key` header:

```
Idempotency-Key: <key>
```

Polytomic uses the key to recognize repeated requests and return the same
response each time.

## How it works

The first request made with a given key determines the outcome Polytomic
records for that key. Every later request that uses the same key returns that same
outcome — including error responses such as `500 Internal Server Error`.
Retries never produce a different result than the original attempt.

## Generating keys

Use a value with enough entropy to avoid collisions. V4 UUIDs or another
random string work well.

Keys must:

* Contain only alphanumeric characters, dashes (`-`), and underscores (`_`)
* Be at least 8 and at most 255 characters long

## Key lifetime

Polytomic retains idempotency keys for at least 24 hours. After that, a key becomes
eligible for removal. Reusing a removed key is treated as a new request, as
if the original had never been made.

## Lock contention

While a request with a given idempotency key is in flight, Polytomic holds
a lock on that key so only one instance of the request runs at a time. This
prevents race conditions on concurrent retries.

> ⚠️ Concurrent retries return `409 Conflict`
>
> If you send a second request with the same idempotency key while the
> first is still being processed, Polytomic returns `409 Conflict`. Wait for the
> first request to finish, then retry.

## When to use idempotency keys

* **`POST` requests** — set `Idempotency-Key` to make retries safe.
* **`GET` and `DELETE` requests** — these are already idempotent. Do not
  set `Idempotency-Key` on them. Duplicate calls may return different
  status codes, but server state is unchanged.