Idempotency is the ability to ensure that the same operation can be made multiple times with the same effect as a single execution. This is critical for building reliable integrations that can safely retry failed requests without creating duplicate resources or triggering unintended side effects.
Use idempotency keys for any operation that creates or modifies resources:
Idempotency keys are supported for POST and PATCH requests only.
When you include an Idempotency-Key header in your request:
x-original-request-id header indicating the response is from cacheAlways use a randomly generated UUID v4 for idempotency keys:
Key Requirements:
Include the Idempotency-Key header in your POST or PATCH requests:
When Deel returns a cached response, you can identify it by checking for the x-original-request-id header:
If you send multiple requests with the same idempotency key while a request is still in progress, you’ll receive a 429 error:
How to handle:
If you intentionally cancel a request and want to retry, wait 2 minutes before using the same idempotency key.
When making critical requests, store the idempotency key in your database alongside the request data:
Benefits:
Always include idempotency keys for operations that create or modify data:
Each unique operation should have its own idempotency key:
Cached responses last for 24 hours. Plan your retry logic accordingly:
For intentional operation retries (not network failures), generate a new key.
Only successful responses (2xx) are cached. Failed requests should be retried:
Possible causes:
Idempotency-Key headerSolution:
Cause: Concurrent requests with same idempotency key
Solution: Wait for Retry-After duration before retrying:
Scenario: First request created wrong resource, want to create a new one
Solution: Generate a new idempotency key:
Test that your integration handles idempotency correctly: