Idempotency Keys

Why

A payment network can drop your response after the charge succeeds. Without idempotency, a retry creates a duplicate charge. Meridian requires an Idempotency-Key header on all state-changing endpoints so every operation is safe to replay.

How it works

1. Generate a unique key (UUID v4) on the client.
2. Send it in the header with your POST/PATCH/DELETE request.
3. Meridian records the response keyed to that value for 24 hours.
4. Any subsequent request with the same key returns the original response — no side effects re-execute.

Example

POST /v1/licenses/activate HTTP/1.1
Host: api.getnimbus.net
Idempotency-Key: 4f8b3a2e-9c1d-4e5f-a6b7-8c9d0e1f2a3b
Content-Type: application/json

{ "license_key": "NIMBUS-XXXX-XXXX-XXXX" }

Rules

• Keys are scoped to the endpoint + payload hash.
• Different payloads require different keys.
• A 409 Conflict is returned if a key is reused with a mismatched body.
• Keys expire after 24 hours; replay after expiry is a fresh request.