Idempotent Requests

The KOMOJU API supports idempotent requests, ensuring that each operation is executed at most once. This is important for customers utilizing automatic retries on failed requests, to avoid for example duplicate captures or refunds.

Idempotent requests are supported for POST API requests. To make use of idempotent requests, clients need generate a unique, non-empty idempotency key per request, and send it in the X-KOMOJU-IDEMPOTENCY header. A random UUID is recommend, but users are free to chose their own formats for convenience. The idempotency key needs to be globally unique for each request. Idempotency keys are limited to 100 ASCII characters in length.

If a request is retried by the client for any reason, the same idempotency key and request body must be used for all retries of that request. If KOMOJU has already processed a request with the supplied idempotency key, the same response will be returned as for the initial request, without performing the requested operation again.

If a request is retried before the initial request has generated a response, a HTTP 409 is returned instead.

⚠️

Warning

Idempotency keys are valid for up to 24 hours after the first use, after which they become available for reuse. By extension, retries more than 24 hours after the initial request are not guaranteed to be idempotent.