Idempotency
Idempotency keys prevent duplicate operations when the same request is retried with the same key. If a request times out or returns an error, you can safely retry it with the same idempotency key.
Idempotency keys are currently supported on payout mutation endpoints. Check the reference docs for each endpoint to see if it accepts an idempotency-key header.
Usage
Include a UUID as the idempotency-key header:
POST /api/payout
idempotency-key: 550e8400-e29b-41d4-a716-446655440000Generate a fresh UUID per operation. Reuse the same key only when retrying a request to ensure that operations are not duplicated.
Behavior
Successful responses are cached and returned for retries with the same idempotency key — Mural sets idempotency-replayed: true on the response header. Failed responses are not cached, so failed requests can always be retried with the same key. Idempotency keys expire after 24 hours; requests using an expired key return a 422 response instead of the cached value, though this is not guaranteed for requests older than 90 days. Generate a new key to retry after expiry.
| Scenario | Status | reason | What to do |
|---|---|---|---|
| Value is not a valid UUID | 400 | — | Use a valid UUID as the idempotency key |
| Same key, different body | 409 | BODY_MISMATCH | Resend with the original body, or use a new key for a different request |
| Same key, different endpoint | 409 | ENDPOINT_MISMATCH | Each key is bound to its original endpoint — use a new key |
| Same key, request in progress | 409 | IN_PROGRESS | Retry with the same key after a short backoff |
| Key expired | 422 | — | Generate a new key and retry |
Updated about 7 hours ago