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:

younium-idempotency-key: [string]
younium-idempotency-durationinhours: [int]

• 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.

• include the younium-idempotency-durationinhours in the request header to specify how long the response should be stored in hours.

Response Headers

The response of an idempotent request includes the following headers:

younium-idempotency-key: [string]
younium-idempotency-durationinhours: 24
younium-idempotency-expires: [UTC date string]

• 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 24 hours if no specified duration is provided.

• maximum duration is one week, 168 hours.

• When the duration expires, 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:

{
    "errors": {
        "message": [
            "Ongoing Request with younium-Idempotency-key: [string]. Wait for initial request to resolve"
        ]
    },
    "title": "An error connected to request idempotency occurred",
    "status": 409,
    "extensions": {
        "traceId": "0HNA5Q8MGHSRR:00000003"
    }
}

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:

{
    "errors": {
        "message": [
            "Request body doesn't match for request with younium-Idempotency-key:[string]"
        ]
    },
    "title": "An error connected to request idempotency occurred",
    "status": 400,
    "extensions": {
        "traceId": "0HNA5Q8MGHSRR:00000003"
    }
}