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.O que acontece em cada caso
Repetição com o mesmo corpo
Repetição com o mesmo corpo
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.
Mesma chave, corpo diferente
Mesma chave, corpo diferente
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 primeira ainda está em andamento
A primeira ainda está em andamento
409. Acontece quando duas tentativas rodam ao mesmo tempo. Aguarde e
consulte o resultado em vez de enviar uma terceira tentativa.Chave longa demais
Chave longa demais
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 emPOST /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.
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.

