---
title: "Idempotency"
description: "Retry a write safely with an Idempotency-Key header."
---

> Documentation Index
> Fetch the complete documentation index at: https://tarkle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

Any `POST`, `PATCH`, `PUT` or `DELETE` under `/api/v1` accepts an optional `Idempotency-Key` header. Use 1 to 255 visible characters. A UUID is a good choice.

- The first request with a key runs, and its answer is kept for 24 hours.
- The same request again (same method, path, query, workspace and JSON body) returns that answer with `Idempotent-Replayed: true` and does nothing twice.
- The same key for a different request is `422 idempotency_key_reused`.
- The same request while the first is still running is `409 idempotency_in_progress` with `Retry-After: 1`.
- A 5xx, a 429 or an answer over 256 KB is not kept, so a retry runs the request again.
- A key belongs to the account that created the token.
- If Tarkle cannot record the key it answers `503 unavailable` and does **not** run the write.
- Reads ignore the header. A malformed key is `400 invalid_request`.

```bash
curl -X POST -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  -H "Idempotency-Key: 5f1c0b7e-3c2a-4d58-9a45-0d7e2a1b6c11" \
  -H "Content-Type: application/json" -d '{"name": "Invoices"}' \
  https://tarkle.com/api/v1/folders
```

Source: https://tarkle.com/docs/api/idempotency/index.mdx