Idempotency-Key header solves this.
How it works
Send a uniqueIdempotency-Key header with any POST request to a /v1/ endpoint. Bachs will:
- Execute the request normally on the first call.
- Cache the response for 24 hours.
- Return the identical cached response on any subsequent request that uses the same key, without executing the handler again.
Using the header
Scope and caching
Non-2xx responses are never cached. If a request fails with a 4xx or 5xx, you can immediately retry using the same key.
Fingerprint mismatch 409
Each idempotency key is bound to the exact request it was first used with (method + path + body). If you reuse a key with a different request body, you will receive a409 CONFLICT:
Choosing good keys
Good
Tied to a specific business operation:
order_ORD-12345withdrawal_2026-05-14_batch-3_item-7checkout_usr_abc_session_xyz
Avoid
Keys that could collide or repeat:
- Random UUIDs regenerated on each retry (defeats the purpose)
- Timestamps alone (collide under load)
- Generic strings like
retry_1
Retry pattern
idempotency_key is used on every retry. If the first request succeeded but the response was lost in transit, the retry returns the cached response. No duplicate is created.
