# Idempotência

> Idempotency-Key em todo POST que cria recurso ou trabalho, guardada por 24 horas, por conta e por operação.

Todo `POST` que cria recurso ou trabalho exige o cabeçalho `Idempotency-Key`. Ele garante que repetir a chamada (por queda de rede, por timeout, por `429`) não cria duas vezes a mesma coisa.

**Regra de uso:** gere **um UUID por operação lógica** e repita o **mesmo UUID** em todas as retentativas dela. Operação nova, UUID novo.

```http
POST /v1/relatorios HTTP/1.1
Authorization: Bearer rmf_test_...
Idempotency-Key: 7f3c1b52-9d4e-4a86-b0c1-2e5d8f6a9b13
Content-Type: application/json
```

## Como funciona

- A chave é **por conta e por operação**: a impressão digital inclui a conta, o método, o caminho e o corpo. A chave de outra conta nunca colide com a sua.
- É guardada por **24 horas**.
- Mesma chave e mesma impressão digital: a resposta original é devolvida, sem criar de novo.
- No envio de arquivo (`multipart/form-data`), a impressão digital é o conteúdo do arquivo e dos demais campos, não o corpo multipart.

## Erros

| Situação | Resposta |
|---|---|
| Faltou o cabeçalho | 400 [`cabecalho_ausente`](/erros/cabecalho_ausente) |
| Mesma chave com outro corpo | 422 [`idempotencia_conflito`](/erros/idempotencia_conflito) |
| Mesma chave ainda em processamento | 409 [`idempotencia_em_andamento`](/erros/idempotencia_em_andamento): espere e repita com a mesma chave |

Reenviar o mesmo **conteúdo** de arquivo pela mesma conta, mesmo com outra `Idempotency-Key`, devolve o arquivo existente com `duplicado: true` (200).