---
url: /topics/idempotent-requests.md
---
# 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](https://www.rfc-editor.org/rfc/rfc4122) 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.

```http
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
```

::: tip 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.