Idempotency Keys

Overview

An idempotency key is a unique token your client generates and attaches to mutation requests. Meridian stores the key alongside the response. If the same key arrives again within the configured window, Meridian returns the cached response instead of re-executing the operation.

When to Use

• Payment capture and refund endpoints
• Subscription lifecycle changes
• License key generation and revocation
• Any POST/PUT where a network retry could duplicate state

Client Implementation

Generate a UUID v4 on the client before the request. Send it in the Idempotency-Key header. Retry with the identical key on timeout or 5xx. Never reuse a key across different payloads.

POST /v1/payments/capture
Idempotency-Key: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
Content-Type: application/json

{
  "payment_id": "pay_9h2K...",
  "amount": 2999
}

Server Behavior

Meridian stores the key and response for 24 hours. Subsequent requests with the same key receive HTTP 200 with the original response body. If the first request is still in-flight, concurrent requests receive HTTP 409 Conflict.

Key Lifecycle