API Reference

Idempotency Keys

Prevent duplicate charges when network failures force clients to retry requests. Send an idempotency key and Meridian guarantees exactly-once processing.

Quick start

Generate a UUID v4 client-side and include it in the X-Idempotency-Key header. Meridian stores the key and its response for 24 hours. Any subsequent request with the same key returns the cached response without re-executing the charge.

curl -X POST https://api.getnimbus.net/v1/charges \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Idempotency-Key: 4f8b3a2e-9c1d-4e5f-a6b7-8c9d0e1f2a3b" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2999, "currency": "usd", "source": "card_..."}'

Behavior

First request

Meridian processes the charge normally and persists the response keyed by your idempotency key. HTTP status reflects the actual outcome.

Subsequent requests

Meridian returns the cached response with the original HTTP status code. The charge is never executed again. Response time is sub-millisecond.

Key expiration

Keys expire after 24 hours. After expiration, the same key submitted again will be treated as a new request and processed normally.

Concurrent requests

If two requests with the same key arrive simultaneously, only one is processed. The other receives a 409 Conflict with the in-flight key status.

Error handling

Status	Meaning
`200`	Request processed successfully (first time or cached replay).
`409`	A request with this key is currently in-flight. Retry with exponential backoff.
`422`	Missing or malformed idempotency key. Must be a valid UUID v4.

Best practices

1Generate a fresh UUID for each distinct operation, not per retry attempt.
2Store the key locally before sending the request so you can retry with the same key after a network failure.
3Use exponential backoff with jitter when retrying 409 responses.
4Never reuse an idempotency key for a different payload. Keys are scoped to the exact request body.