> ## 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 cabeçalhos Idempotency-Key estáveis em requisições de escrita para que as tentativas permaneçam seguras e deduplicadas.

# Idempotência

Todos os endpoints de mutação `POST` e `PATCH` aceitam um cabeçalho opcional `Idempotency-Key`.

## Quando enviar

Use uma chave de idempotência quando:

* Um cliente pode tentar novamente após uma falha de transporte.
* Um worker de fila pode despachar a mesma operação lógica mais de uma vez.
* Um agente de IA pode executar novamente uma mutação após progresso parcial ou novas tentativas de ferramentas.

## Padrão recomendado

* Gere uma chave estável por mutação lógica.
* Reutilize a mesma chave nas tentativas dessa mutação.
* Altere a chave quando a mutação pretendida mudar.

## Exemplos

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

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

## Boas delimitações

* Uma chave para criar um projeto.
* Uma chave diferente para exportar esse projeto.
* Outra chave diferente para atualizar as configurações do projeto.

Isso mantém as tentativas seguras sem deduplicar acidentalmente trabalhos não relacionados.