Idempotency - My Crypto Server

Mutating endpoints (POST, PATCH, DELETE) accept an optional Idempotency-Key header. When you supply one, the server caches the response for 24 hours and replays it verbatim on retries — so a network timeout or process crash can’t cause a duplicate payment link, session, or webhook endpoint.

POST /api/v1/checkout_sessions
Authorization: Bearer ck_live_...
Idempotency-Key: order-123-checkout-v1
Content-Type: application/json

Key requirements

Unique per request — use a value tied to the operation, not a random UUID you generate on every retry. A good pattern: {orderId}-{operation}-{version}.
String, any format — up to 255 characters.
Scope — idempotency is scoped per API key. The same key used by two different API keys is treated as two independent operations.

Replay behavior

When the server returns a cached response, the reply includes the header:

Idempotent-Replayed: true

The status code and body are identical to the original response.

Conflict: different body, same key

If you send the same Idempotency-Key with a different request body, you get a 409 conflict:

{
  "error": {
    "type": "conflict",
    "code": "idempotency_key_reused",
    "message": "Idempotency-Key already used with a different request body",
    "requestId": "req_..."
  }
}

This is a guard against accidental key reuse. If you hit this, either fix the key or use a new one.

When to use it

Always use Idempotency-Key for operations where duplicates matter:

Creating a checkout session for a specific order
Creating a payment link for a product
Creating a webhook endpoint during setup

You can omit it for exploratory reads or one-off operations where duplicates are harmless.

​Key requirements

​Replay behavior

​Conflict: different body, same key

​When to use it

Key requirements

Replay behavior

Conflict: different body, same key

When to use it