Idempotent requests
All POST endpoints in the API support idempotency. This mechanism ensures that requests are treated identically when retried and return the same response as the initial request. This prevents duplicate operations and unintentional actions in case of network failures or other disruptions.
How Idempotency Works
Idempotency is implemented by storing the response of a request linked to a unique idempotency key and its endpoint. Any subsequent request with the same idempotency key to the same endpoint will receive the stored response instead of re-executing the operation.
Using the Idempotency Key
To utilize idempotency, include the younium-idempotency-key
in the request header:
All POST requests support idempotency keys.
If an idempotency key is provided in other HTTP methods, it will be ignored.
The idempotency key is a string for flexibility, but using a UUID or a unique key is recommended to prevent collisions.
The same idempotency key can be used across different endpoints, as uniqueness is determined in combination with the endpoint.
Response Headers
The response of an idempotent request includes the following headers:
younium-idempotency-key
: The same key that was provided in the request.younium-idempotency-durationinhours
: storage duration in hours,younium-idempotency-expires
: The UTC timestamp when the stored response will expire.
Expiry and Storage
The result of an idempotent request is stored for 48 hours.
After 48 hours, a request with the same idempotency key will be treated as a new request.
Responses for both successful and unsuccessful requests are stored and will contain the corresponding
younium-idempotency
headers.
Benefits of Idempotency
Prevents duplicate entries or actions due to network retries.
Ensures safe request repetition without unintended side effects.
Improves system reliability by reducing inconsistencies caused by transient failures.
Potential Errors Related to Idempotency
Failing Request
Requests that fail before reaching the endpoint will not be treated as idempotent and will never include the idempotency headers. This is generally the case for:
Failed authentications or authorizations (401, 403)
Not found endpoints (404)
Errors caused by factors outside the application (e.g., infrastructure-related failures)
Ongoing and Concurrent Requests
If two or more requests with the same key are sent at the same time, the first request must resolve before a response can be returned. The second request will therefore wait for the first request to resolve and return the stored response once available. If the second request fails to wait for a result, it will return a 409 Conflict error with no younium-idempotency
headers.
Example Response:
Altered Request Body
If the request body is modified from the initial request, a 400 Bad Request error response will be returned with no younium-idempotency
headers.
Example Response:
Last updated
Was this helpful?