Idempotent Requests
The API supports idempotency to allow safe retries of requests without accidentally performing the same operation twice. This is particularly useful for POST requests when creating or updating resources, such as billing products. By including an idempotency key in your request, you can retry it after a network failure without risking duplicate resources or unintended updates.
To perform an idempotent request, include an x-idempotency-id header with a unique key in your POST request. The client generates this key, and the server uses it to identify retries of the same request. We recommend using V4 UUIDs (e.g., 550e8400-e29b-41d4-a716-446655440000) or another random string with enough entropy to avoid collisions. The x-idempotency-id value can be up to 255 characters long.
How It Works
When a request with an x-idempotency-id is received, the API stores the response (status code and body) of the first attempt associated with that key—whether it succeeds or fails. Subsequent requests with the same key return the cached result, including 500 errors, ensuring consistent behavior. Results are only saved after the endpoint begins execution. If validation fails or a concurrent request conflicts, no result is cached, and you can retry safely.
Keys expire and are removed from the system after 24 hours. If a key is reused after expiration, it’s treated as a new request. If a reused key matches a prior request’s parameters before expiration, the API will reject it to prevent misuse.
- Use
x-idempotency-idonly withPOSTrequests to endpoints like{{BASE_URL}}/v1/api/billing/products. Avoid withGETorDELETE, as they’re inherently idempotent. - Retry safely on network issues, validation failures, or concurrency conflicts—no result is cached in these cases.
- Ensure key uniqueness per operation to prevent collisions. Reusing a key with different parameters before expiration triggers an error.