Skip to main content
Quando uma requisição dá timeout, você não sabe se ela chegou à API. Se repetir sem cuidado, o recurso pode ser criado duas vezes. Em POST /messages, o cliente final recebe a mesma mensagem duas vezes. Com o header Idempotency-Key, a primeira chamada é executada e as repetições recebem a mesma resposta da primeira vez.
string
Chave única da operação, com até 200 caracteres. Aceita em POST e PUT. É opcional: sem ela, cada chamada é executada normalmente.

Como usar

Gere um identificador único para cada operação de negócio e use esse mesmo identificador em todas as tentativas daquela operação. Com a mesma chave, a API entende que as tentativas são uma única operação.
As melhores chaves vêm de algo que já é único no seu sistema, como pedido-88213-confirmacao, fatura-2026-09-lembrete ou crm-card-771-nota. Um UUID aleatório também serve, desde que você o salve antes da primeira tentativa. Se um UUID novo for gerado a cada tentativa, a chave não protege contra duplicidade.

O que acontece em cada caso

A API devolve a resposta da primeira execução, com o mesmo status, e acrescenta este header:
Nada é executado de novo. É o que acontece no retry depois de um timeout.
A API recusa a requisição com 409. Usar a mesma chave em outra operação quase sempre indica um erro na forma como a sua integração gera as chaves.
A resposta também é 409. Acontece quando duas tentativas rodam ao mesmo tempo. Aguarde e consulte o resultado em vez de enviar uma terceira tentativa.
Com mais de 200 caracteres, a requisição é recusada com 400 ERR_API_IDEMPOTENCY_KEY_INVALID antes de qualquer execução.

Regras da chave

Erros não ficam guardados. Só as respostas de sucesso são registradas. Se a chamada falhou por dado inválido, corrija o corpo e repita com a mesma chave, porque a operação ainda não aconteceu. A chave vale por token, método e rota. A mesma chave usada em POST /messages e em POST /contacts conta como duas operações diferentes, sem conflito. Tokens diferentes também não compartilham chave, mesmo sendo da mesma empresa. Resposta sem corpo também é repetida. Operações que respondem 204, como aplicar uma tag no atendimento, guardam o resultado igual às demais, e a repetição devolve 204 com Idempotent-Replay: true. Envio com arquivo não usa a chave. Em multipart/form-data, o arquivo ainda não foi lido quando a verificação acontece, então não há corpo para comparar e a chave é ignorada. Vale para envio de mídia, campanha com arquivo e anexo de agendamento: nesses casos, trate a duplicidade do seu lado. A chave tem prazo. As chaves ficam guardadas por 24 horas (esse prazo pode ser configurado na instalação). Depois disso, a mesma chave faz a operação ser executada de novo. A proteção serve para os retries feitos logo depois de uma falha. Um reenvio feito semanas depois é tratado como uma operação nova.
Se houver uma instabilidade interna, a API processa a requisição normalmente, sem a proteção de idempotência, em vez de recusá-la. Por isso, operações críticas também devem conseguir identificar duplicidade do seu lado.

Onde usar

POST /messages

É onde a duplicidade aparece para o cliente final. Use sempre.

POST /campaigns

Uma campanha criada duas vezes dispara para toda a base duas vezes.

POST /contacts

Evita cadastro duplicado quando o retry vem de uma rotina automática. Veja também POST /contacts/upsert.

POST /crm/cards

Cards repetidos poluem o painel do CRM e distorcem os indicadores.