> ## Documentation Index > Fetch the complete documentation index at: https://docs.pombo.digital/llms.txt > Use this file to discover all available pages before exploring further. # Idempotência > Repita uma chamada sem enviar a notificação duas vezes, e saiba quando tentar de novo. Uma cobrança enviada duas vezes é um problema jurídico, não só um custo. Se a sua chamada cair na rede, você fica sem saber se ela chegou. A `Idempotency-Key` resolve isso: você repete, e o Pombo reconhece a repetição, devolve a notificação original e **não envia de novo**. O cabeçalho é opcional, mas vale mandar sempre. Sem ele, cada chamada cria uma notificação nova: se você repetir uma requisição cuja resposta não chegou, o destinatário recebe duas notificações e você paga dois envios. E não há como desfazer, porque uma notificação extrajudicial emitida não pode ser cancelada. ## Como usar Envie o cabeçalho em `POST /notifications`. Uma chave por notificação, gerada por você, estável entre as tentativas. Letras, dígitos, sublinhados e hifens, até 255 caracteres; qualquer outro caractere devolve `400`. ``` Idempotency-Key: cobranca-2026-08-31-0001 ``` | Chamada | Resposta | | --------------------------------------------- | -------------------------------------------------------------------- | | Primeira, chave `K`, corpo `P` | `201` com a notificação criada | | Repetição, chave `K`, corpo `P` | `200` com o corpo original e o cabeçalho `Idempotent-Replayed: true` | | Chave `K`, corpo diferente | `409` com `error_code` igual a `IDEMPOTENCY_KEY_REUSED` | | Chave `K`, mesmo corpo, **arquivo diferente** | `409`, igual ao caso acima | A diferença entre `201` e `200` é o sinal mais barato que existe: um `200` significa que nada novo foi criado e nenhum envio foi descontado. Com anexo, o arquivo entra na conta. Dois documentos diferentes sob a mesma chave nunca podem ser confundidos com a mesma notificação, por isso o segundo é `409` e não uma repetição. A resposta traz `idempotency_key`, a chave que você enviou. **O resumo do pedido não é devolvido:** o Pombo guarda um `sha256` do envio internamente e é com ele que decide entre devolver a original e recusar com `409`. É um detalhe de deduplicação, não parte do contrato. **A `Idempotency-Key` vale só em `POST /notifications`.** Em `POST /templates` o cabeçalho é ignorado, e repetir a chamada **cria um segundo modelo**: o Pombo renomeia o nome repetido sozinho, acrescentando `-2`, `-3`, em vez de recusar o conflito. Como a API não lista modelos, esse segundo modelo fica inalcançável: você não recebeu o `template_id` dele e não há como consultá-lo depois. Se a resposta de `POST /templates` não chegar, **não repita às cegas**. Em WhatsApp o modelo duplicado ainda vai para aprovação da Meta. ## Quando tentar de novo | Situação | O que fazer | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | Erro de rede, timeout, `500`, `502`, `503` | Repita com a mesma chave. Se o envio levava anexo, mande também o mesmo arquivo: sem os mesmos bytes não há como confirmar uma repetição | | `429` | Espere e repita. Veja [Limites de uso](/api/limites-de-uso) | | Qualquer `4xx` fora `429` | **Não repita.** A requisição precisa mudar antes | Um `500` em `POST /notifications` não garante que nada foi enviado, e é justamente por isso que repetir com a mesma chave é seguro: se o envio já tinha acontecido, você recebe a notificação original em vez de uma segunda. Repetir um `4xx` sem mudar nada só gasta requisição. A resposta diz o que corrigir, e a lista está em [Erros](/api/erros). **Para repetir um envio que falhou, use uma chave nova.** A chave é gravada uma única vez e nunca é liberada, então reaproveitá-la devolve a falha original em vez de tentar de novo. Uma repetição idempotente também não desconta nada: ela não cria uma notificação, devolve a que já existia.