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

# Idempotency

> Use stable Idempotency-Key headers on write requests so retries stay safe and deduplicated.

# Idempotency

All `POST` and `PATCH` mutation endpoints accept an optional `Idempotency-Key` header.

## When to send it

Use an idempotency key when:

* A client may retry after a transport failure.
* A queue worker may dispatch the same logical operation more than once.
* An AI agent may re-run a mutation after partial progress or tool retries.

## Recommended pattern

* Generate one stable key per logical mutation.
* Reuse the same key for retries of that mutation.
* Change the key when the intended mutation changes.

## Examples

```http theme={null}
Idempotency-Key: create-project-song-1
```

```http theme={null}
Idempotency-Key: export-song-1
```

## Good boundaries

* One key for creating a project.
* A different key for exporting that project.
* A different key again for updating project settings.

This keeps retries safe without accidentally deduplicating unrelated work.