Overview
Idempotency is achieved by including a uniqueIdempotency-Key
header in your HTTP requests. Straddle then uses this key to detect and prevent duplicate operations. If a request with a given key has already been processed, Straddle will return the original response without re-executing the operation.
Idempotency is currently supported for POST and PATCH requests only and requires API key authentication.
How it Works
When you send a request with anIdempotency-Key
header:
- Straddle checks if a request with that key has been seen before.
- If it’s a new key, the request is processed normally. The key and the request’s details (path, method, body hash) are stored.
- If the key has been seen before:
- If the previous request with that key is still in progress, a
409 Conflict
error is returned, indicating a concurrent request. - If the previous request completed and the requests are identical, the original response is replayed with an
Idempotent-Replayed: true
header. - If the idempotency key is reused for a non-identical request, a
409 Conflict
error is returned, indicating that the key has been reused for a different request.
- If the previous request with that key is still in progress, a
- Idempotency keys are only stored for a limited period of time (~24 hours).
Using Your Idempotency Key
To make an idempotent API request, include a unique string in theIdempotency-Key
header. We require a key length of 10-40 characters.
Here’s an example of how to include the Idempotency-Key
header in your API requests:
Response Headers (Replayed)
When an identical request is successfully replayed, the response will include the original HTTP status code, original response headers, and the original response body, with an additional header:Handling Idempotency Errors
Straddle will return specific409 Conflict
errors in idempotency-related scenarios:
Idempotency Key Reused for a Different Request
If you send a request with anIdempotency-Key
that was previously used for a different request (e.g., different path, method, or request body), you will receive a 409 Conflict
error.
Idempotency-Key
for each distinct logical operation.
Concurrent Request in Progress
If you send a request with anIdempotency-Key
that is currently being processed by another request, you will receive a 409 Conflict
error.
Invalid Idempotency Key
If theIdempotency-Key
header is supplied and does not meet the length requirements (10-40 characters), a 400 Bad Request
error will be returned.
Idempotency-Key
is present and meets the specified length requirements.
Best Practices
- Generate Unique Keys per Business Operation: For each distinct business operation you initiate, generate a new and unique
Idempotency-Key
. Do not reuse keys across different logical actions. - Use UUIDs: Universally Unique Identifiers (UUIDs) are an excellent choice for generating idempotency keys due to their high probability of uniqueness.
- Handle 409 Conflicts: Implement logic in your client to properly handle
409 Conflict
responses. For “key already used for a different request,” generate a new key. For “previous identical request currently in progress,” consider retrying. - Key Length: Ensure your
Idempotency-Key
is between 10 and 40 characters long. - Avoid Sending Same Key with Different Data: Never send the same
Idempotency-Key
with a different request body, path, or HTTP method. This will result in a409 Conflict
error.