Skip to main content

​
Overview

A timeout or dropped connection can leave you unsure whether a request reached Lead. Send an Idempotency-Key header and you can retry the same request as many times as you need. If the first attempt succeeded, Lead returns the same response again and takes no new action. If it failed, Lead evaluates the retry as a new request. One rule governs everything on this page: Lead caches only successful (2xx) responses. Errors are never cached.

​
Sending a key

Include an Idempotency-Key header with a value you generate.
  • Format. Any string up to 255 characters. Lead recommends a v4 UUID or another random value.
  • Scope. A key is scoped to one endpoint within one program. The same string on POST /v2/wires and POST /v2/entities does not collide, and keys in one program never collide with keys in another.
  • Expiry. A key is valid for 48 hours from the original request. After that, Lead treats the same key as a new request.

​
Which endpoints accept a key

All mutative endpoints require an Idempotency-Key. The API reference lists the header on every endpoint that supports it and marks whether it is required. Lead recommends sending a key on every request that creates an object, whether or not the endpoint requires one. A request without the header to an endpoint that requires it returns 400 idempotency_key_missing.

​
How Lead handles a repeated key

The replayed response is byte-for-byte the original, including id, status, and timestamps as they were at creation. To see the object’s current state, retrieve it by id.

​
Retrying after an error

Because Lead never caches an error, you do not need to rotate to a new key before retrying. Fix the request if the error was yours (a 400 or 422 naming a field), or simply resend if the condition was temporary. For example, a request rejected with non_sufficient_funds can be retried with the same key once the balance is covered. If you built key-rotation logic against v0 or v1, where some 4xx responses were cached, you can remove it on v2.

​
Asynchronous requests

Many payment creates return 202 Accepted and then settle, reject, or return later. Idempotency covers the create, not the outcome. A 202 is cached as a success, and a later downstream failure does not invalidate it; retrying the same key returns the original 202. Track the outcome through webhooks or by retrieving the object.
  • API Errors: the idempotency_* codes above and every other code v2 returns
  • Webhooks: how to learn the final state of an asynchronous request