Idempotency

The Quarzo API supports idempotency to let you safely retry requests without risking duplicate operations - for example, sending the same transfer twice after a network timeout. When creating or updating an object, idempotency key is mandatory. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice.

How to use it

Add an Idempotency-Key header to any POST request. We recommend using a V4 UUID or equivalent and generate a new one for each distinct operation. Avoid using sensitive data (for example, email addresses or personal identifiers) as idempotency keys.

POST /v1/investment/policies/{policyId}/compartments HTTP/1.1
Host: api.quarzo-life.com
Authorization: Bearer <token>
X-Quarzo-Life-Idempotency-Key: 123e4567-e89b-12d3-a456-60984f46cb48
Content-Type: application/json

GET and DELETE requests

These are inherently idempotent. Setting an Idempotency-Key on them has no effect and is not supported.

Retry logic

Retry with the same key if the request fails with any of the following:

Condition	Retry?
Network error (no response received)	✅ Yes
409 Conflict - request still in progress	✅ Yes
429 Too Many Requests	✅ Yes
5XX server error	✅ Yes
4XX client error (other than 409 / 429)	❌ No - same result every time

Error cases

409 Conflict - the original request is still being processed. Wait briefly and retry with the same key.

422 Unprocessable Entity - the retry body differs from the original request. Each key is bound to an exact request; reuse it only with identical parameters.