Idempotency

Introduction & Definition

What is Idempotency?

Idempotency ensures that performing the same operation multiple times produces the same result without causing unintended side effects. This is especially important in scenarios like payment processing, where duplicate operations could lead to issues such as double charging.

Why It Matters:

In environments where network issues or retries are common, idempotency guarantees that a single operation is processed only once, even if it's requested multiple times.

For example, if creating a payment fails due to a network error, you can safely create the payment again, passing the same idempotency key and assume the payment will occur exactly once, regardless of the number of calls.

An Idempotency-Key can be passed in the request header header as any UUID, although we recommend using UUID Version 4.

Error Handling & Edge Cases

Multiple Requests with the same body and idempotency key:

Creating multiple requests with the same idempotency key and request body will always return the same object as the first request instead of creating a new one. There is no validity period for idempotency keys.

Mismatched Request Parameters:

If an idempotency key is reused with different parameters, our server will return an error indicating that the request parameters don't match the original request associated with that key.

Timeouts & Key Expiry:

Our idempotency keys are valid for a specific period. If a key expires or if a request times out, subsequent requests will need to use a new key. In these cases, our server handles the situation to ensure that only valid and current requests are processed.

Standardized Responses:

When conflicts or errors occur, our server will return an HTTP 409 Conflict status along with a clear error message detailing the issue.

{
    "errorCode": "INVALID_REQUEST_DATA",
    "message": "Payment with given idempotency key was already created with different payload"
}