Skip to content
GLORESEND

Guides

Idempotency

Retry requests safely: a request that can move money is executed at most once per Idempotency-Key.

POST /transfers and POST /test/fund require an Idempotency-Key header. Use a new random value (for example a UUID v4) for each distinct operation, and reuse it when retrying that same operation after a network error or timeout.

Header
Idempotency-Key: 5f0c6a52-3b1e-4c8e-9a51-0e3d7b0f9a11

Behaviour

  • Keys are scoped to your organization and environment and kept for 24 hours. They are 1–255 printable ASCII characters.
  • A retry with the same key and the same request returns the original status and body, with the header Idempotent-Replayed: true. This includes final failures such as insufficient_funds, provider_timeout and provider_error.
  • The same key with a different body or endpoint returns 422 idempotency_key_reuse.
  • While the first request is still running, a concurrent retry returns 409 idempotency_in_progress. Wait and retry.
  • Requests that fail validation do not consume the key: fix the request and send it again with the same key.
  • Errors that mean the operation never ran — for example live_operations_disabled or an unexpected internal_error — release the key so it can be retried.

Recommended retry strategy

Retry on network errors, 409, 429 and 5xx with exponential backoff and the same Idempotency-Key. Do not retry other 4xx responses without changing the request.