The API supports idempotency to ensure safe retries of requests without unintentionally duplicating operations. By including an idempotency key when creating or updating resources, you can safely resend a request after a connection error without creating duplicate resources or applying updates multiple times.

​
Using Idempotency Keys

To make an idempotent request, include the X-Qonto-Idempotency-Key header with a unique value. The client generates this key, which the server uses to identify and process retries of the same request. We recommend using a V4 UUID or another random string with sufficient entropy to prevent collisions. Example: 
X-Qonto-Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

​
How Idempotency Works

When you send a request with an idempotency key, the server caches the successful response for that key. Any subsequent requests using the same key return the cached response, even if the request body differs. This ensures consistent outcomes for retried requests.

​
Key Points

  • Idempotency keys expire after 30 minutes. Sending the same request with the same key after this period creates a new resource.
  • Avoid reusing idempotency keys for different requests to prevent unintended results.

​
When to Use Idempotency Keys

The documentation specifies when you can use the X-Qonto-Idempotency-Key header and lists the endpoints where it applies. For these endpoints, including the idempotency key is a mandatory requirement.