---
updatedAt: 2026-10-29T11:39:31.000Z
agentTools:
  projectIndex: https://docs.sivo.com/llms.txt
---

# Idempotent Requests

Idempotency lets clients safely retry a write without performing the same operation twice. When a client sends a `POST`, `PATCH`, `PUT` or `DELETE` request with an `Idempotency-Key` header, Sivo stores the result of the first request under that key and returns the same result to any retry that uses the same key and identical parameters (same method, path and body).

### Use cases

* Network timeouts or transient errors: retry the same request with the same `Idempotency-Key` to receive the original result.
* Client crashes between request and response: resend the request with the same key to avoid duplicate creations or updates.

### How it works

1. The client generates a unique key per operation (for example, a v4 UUID or another high-entropy random string). Keys can be up to 256 bytes.
2. The client sends the request with:
   * all request parameters and body exactly as intended
   * the `Idempotency-Key` header set to the generated key
3. Sivo processes the first request, then stores its HTTP status, headers and body under the key.
4. A retry with the same `Idempotency-Key` and identical parameters returns the stored status, headers and body without running the operation again. Replayed responses carry an `Idempotency-Replayed: true` header.

Keys are scoped to your organization and mode (`live` or `snbx`), so two organizations using the same key never see each other's results.

### Parameter matching

* Sivo compares the method, path and body of each retry with the first request for that key.
* If they differ, the request is rejected with `422 Unprocessable Entity`. The key stays bound to the first request until it expires, so a changed request needs a new key.

### Key lifetime and reuse

* Keys expire 24 hours after the first request. A request that reuses an expired key is treated as new and processed again.
* To avoid collisions:
  * Generate keys with sufficient entropy.
  * Do not reuse keys across different operations.

### Concurrency

* If a retry arrives while the first request with the same key is still running, it is rejected with `409 Conflict` and a `Retry-After: 1` header. Wait and retry with the same key to receive the original result.
* If the first request never finishes on Sivo's side, the key is released once the 300-second request timeout has passed, and a retry is processed again.

### Error behavior

* Failed requests (any non-2xx response) are not stored. Retrying them with the same key runs the operation again.
* Responses larger than 400 KB are not stored, so a retry of such a request runs it again.

### Guidelines for developers

* Generate one `Idempotency-Key` per logical operation (for example, "draw principal" or "update an organization").
* Keep the key until you receive a final response or your retry window ends.
* Retries should reuse the same key and identical parameters.
* Do not share keys between unrelated operations.

### Examples

Draw principal (retry-safe)

```
POST /debt-lines/dline_cm0v8p2xk0001/draw
Idempotency-Key: 8f0f6e3d-3b2a-4c2d-9ad9-7f8a1b9c77b1

{
  "amount": 5000000,
  "description": "August working-capital draw"
}
```

* First attempt: returns the created draw.
* Retry after a timeout: returns the same status, headers and body, with `Idempotency-Replayed: true`, and no second draw.

Parameter mismatch

```
POST /debt-lines/dline_cm0v8p2xk0001/draw
Idempotency-Key: 8f0f6e3d-3b2a-4c2d-9ad9-7f8a1b9c77b1

{
  "amount": 6000000,
  "description": "August working-capital draw"
}
```

Result: `422 Unprocessable Entity`, because the body does not match the first request for this key. Send the changed request with a new key.

Key reuse after expiry

If you reuse a key more than 24 hours after its first request, Sivo processes the request as new and stores the fresh result under that key.

### Recommendations

* Prefer v4 UUIDs for keys; any random, high-entropy string works.
* Treat keys as sensitive data. Do not expose them to untrusted clients unless your architecture requires it.
* Use one key per operation; never use the same key for different operations.

### FAQ

* Do retries return the same headers? Yes: a replay returns the stored status, headers and body, plus `Idempotency-Replayed: true`. Headers added per request (for example, request identifiers) may differ.
* How long are keys kept? 24 hours after the first request.
* Do `GET` requests need a key? No. Reads are safe to retry as they are, and the header is ignored on them.