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

# Idempotência

> Repita requisições de envio com segurança usando o header Idempotency-Key.

Falhas de rede acontecem: sua requisição pode ter chegado à Superlead mesmo que a resposta nunca tenha chegado a você. Sem proteção, repetir o envio duplicaria a mensagem para o lead.

Para evitar isso, mande o header `Idempotency-Key` em `POST /v1/messages` com um valor único por operação (um UUID, ou o id da operação no seu sistema):

```bash theme={null}
curl -X POST https://api.superlead.app/v1/messages \
  -H "Authorization: Bearer sl_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-8734-confirmacao" \
  -d '{ "to": "+5511999999999", "type": "text", "text": { "body": "Pedido confirmado!" } }'
```

## Comportamento

| Situação                                                  | Resultado                                                                               |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Primeira requisição com a chave                           | Processada normalmente.                                                                 |
| Repetição com a **mesma chave e mesmo corpo**             | Retorna a **mesma resposta** original, sem enviar de novo.                              |
| Mesma chave com **corpo diferente**                       | `409 idempotency_conflict` — a chave identifica uma operação, não pode ser reutilizada. |
| Repetição enquanto a original **ainda está em andamento** | `409 idempotency_conflict` com header `Retry-After` — aguarde e repita.                 |

* As chaves de idempotência são escopadas por empresa e expiram em **24 horas**. Depois disso, o mesmo valor é tratado como uma operação nova.
* Respostas de erro determinísticas (4xx) também são memorizadas e repetidas no replay. Erros transitórios (5xx, falha de rede com o WhatsApp) **liberam** a chave, permitindo um retry real.

## Recomendação

<Tip>
  Derive a chave da operação de negócio, não do momento do envio: `pedido-8734-confirmacao` garante uma única mensagem de confirmação por pedido, mesmo que o seu fluxo rode duas vezes.
</Tip>