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.

How to use it

Add an Idempotency-Key header to any POST or PATCH request. We recommend using a V4 UUID or equivalent and generate a new one for each distinct operation.

POST /v1/subscriptions HTTP/1.1
Host: api.quarzo-life.com
Authorization: Bearer <token>
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

Replayed responses

When the API returns a cached result from a previous request, the response includes:

Idempotent-Replayed: true

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.