Skip to main content
Network failures happen. Without idempotency, retrying a failed POST request can create duplicate charges, duplicate withdrawals, or other unintended side effects. The Idempotency-Key header solves this.

How it works

Send a unique Idempotency-Key header with any POST request to a /v1/ endpoint. Bachs will:
  1. Execute the request normally on the first call.
  2. Cache the response for 24 hours.
  3. Return the identical cached response on any subsequent request that uses the same key, without executing the handler again.
This means you can safely retry a request after a timeout or network error without worrying about double-charging a customer or creating a duplicate withdrawal.

Using the header

The key must be a string. We recommend using a value that naturally ties to the operation for example, your internal order ID combined with an attempt counter.

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 a 409 CONFLICT:
This protects against accidentally reusing a key for a different operation. If you receive this error, generate a new unique key for your new request.

Choosing good keys

Good

Tied to a specific business operation:
  • order_ORD-12345
  • withdrawal_2026-05-14_batch-3_item-7
  • checkout_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

The same 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.