Understanding idempotency
The Idempotency-Key header prevents duplicate payments or transfers when a request is retried.
Important: Idempotency is a mandatory requirement for every API integration that uses POST requests. Integrations that do not implement idempotency, or implement it incorrectly, will not be certified, and API access will not be enabled in production until the issue has been resolved.
How it works
- Generate a unique UUIDv4
Idempotency-Keyfor each request. - If a request fails or you receive an uncertain response, retry it with the same key - the API will return the original result without processing the operation again.
- Use a different key for each distinct operation. Reusing a key with a different payload will return a
422error.
curl --request POST \
--url https://api-sandbox.fuse.com/v1/payments \
--header 'authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Idempotency-Key: <YOUR_IDEMPOTENCY_KEY>' \
--header 'content-type: application/json' \
--data '{}'
Idempotency Errors
| Status Code | Error Type | Detail | Solution |
|---|---|---|---|
| 400 | Bad Request | Idempotency-Key was not provided or is not a valid UUIDv4. | Provide a valid UUIDv4 in the Idempotency-Key header. |
| 409 | Conflict | A request with the same key has started but not yet completed. | Wait for the original request to complete, then retry. |
| 422 | Unprocessable Entity | The same key was used with a different request payload. | Generate a new key and try again. |
Updated 12 days ago
What’s Next
Ready to start making requests?
Did this page help you?