Idempotency
Idempotency ensures that retrying the same request does not create multiple resources or double-execute an action.
Stables follows the standard HTTP idempotency pattern:
Idempotency Key Header
Endpoints that create or change a resource require an Idempotency-Key header. Use a new unique value (for example a UUID) for each distinct operation, and reuse it only when retrying that same operation.
Idempotency-Key: 12bd9e7c-02fe-4ea9-84e2-52264aaf8790Which Endpoints Require It
The header is required on:
- Transfer creation, and the sandbox transfer deposit simulation
- Quote creation
- Customer creation, verification links, and customer metadata updates
- Entitlement requests and entitlement requirement submissions
- RFI evidence submission
- Virtual account creation, destination updates, PayID registration, and whitelist account creation and updates
- Webhook creation and deletion
- API key creation and revocation
Each endpoint's API reference shows whether Idempotency-Key is required. On these endpoints a request without the header is rejected with 400 Bad Request and the message Missing Idempotency-Key header. Other endpoints ignore the header.
Idempotency Guarantees
| Behavior | Guarantee |
|---|---|
| Suppressed duplicates | Only the first request executes |
| Same response returned | Retries of a successful (2xx) request return the original status code and body |
| Failures are not kept | If the original request failed (any non-2xx response), a retry with the same key runs again |
| Concurrent retries | A retry sent while the original is still processing returns 409 Conflict (Idempotent request already in progress) |
| Stored for 24 hours | Based on Stables platform retention |
Keys are scoped to your organisation and to the kind of operation, so the same key sent to, say, Create Quote and Create Transfer is treated as two separate requests.
On most endpoints the request body is not compared on replay. Reusing a key with a different body returns the response stored for the first request, without applying the new body. The sandbox deposit simulation is the exception: reusing a key there with a different body returns 409 Conflict (Idempotency-Key corresponds to a different request payload).