Idempotent requests

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.