Idempotent requests

Networks fail between "server did the work" and "client got the response." Without idempotency, retrying a POST can create the resource twice. The Idempotency-Key header makes retries safe.

How it works

• Send a unique key per logical operation - UUID, or your own internal ID (signup_10492_project).
• On retry, repeat the same key and identical body.
• Meridian returns the original stored response - including its status code - instead of executing again.

Semantics

HTTP/1.1 201 Created
Idempotent-Replay: true

SDK behavior

All official SDKs attach a key automatically to every POST - retries within the SDK's maxRetries reuse it, so default SDK calls are already safe:

await client.projects.create(params);                       // auto key
await client.projects.create(params, {
  idempotencyKey: `provision-${customerId}`,                // yours instead
});

Choosing keys

• Derive from your operation ID, not a random per-request value - that's what makes cross-restart retries dedupe correctly. Good: provision-customer-884. Bad: Math.random().
• One key per logical operation; a second operation needs a new key even if the body is identical.

The conflict error

{
  "error": {
    "type": "conflict",
    "code": "idempotency_conflict",
    "message": "This idempotency key was already used with a different request body.",
    "request_id": "req_2hF8kLm4xQ"
  }
}

If you get this, the key was already consumed by a different payload - generate a fresh key. This is what prevents "same key, different intent" bugs from silently replaying.