Idempotência

Quais rotas aceitam uma chave de idempotência e como repetir um pedido sem duplicar envios nem cobranças.

Redes falham: a sua chamada pode chegar à API e a resposta se perder no caminho. Algumas rotas, as que enviam mensagens, cobram ou executam ações em massa, aceitam uma chave de idempotência: repetir o pedido com a mesma chave devolve o resultado do primeiro, sem fazer tudo de novo.

A API não tem idempotência geral. Só as rotas da tabela abaixo usam chave; nas demais, repetir um POST pode criar outro recurso.

Rotas que aceitam chave

RotaOnde vai a chaveObrigatóriaRegras
POST /email/transactional/messagesCampo idempotency_key do corpo ou cabeçalho Idempotency-Key (vale o do corpo quando os dois vêm)SimDe 1 a 256 caracteres ASCII imprimíveis. Única por workspace, sem prazo de expiração.
POST /email/outreach/conversationsCampo idempotency_key do corpoSimGere uma vez por e-mail composto.
POST /leads/actionsCabeçalho Idempotency-KeySimAté 128 caracteres.
POST /google-sheets/{id}/rowsCabeçalho Idempotency-KeySimÚnica por usuário.
POST /user/invoicesCampo idempotencyKey do corpoNãoDe 1 a 64 caracteres entre letras, números, _ e -.

A descrição de cada rota, na Referência da API, explica o que acontece em cada repetição.

Como usar

  1. Gere a chave antes da primeira tentativa e guarde-a junto com o registro que originou o pedido, por exemplo recibo-pedido-1234 ou um UUID.
  2. Envie o pedido com a chave.
  3. Se a conexão cair, a chamada estourar o tempo ou a resposta for 502 ou 503, repita o mesmo pedido com a mesma chave.
  4. Para um pedido novo, use uma chave nova.

Não troque a chave para "forçar" um pedido que pareceu falhar: se o primeiro tiver dado certo, ele acontece duas vezes.

Exemplo: e-mail transacional

SituaçãoResposta
Mesma chave, mesmo pedido200 OK com o mesmo resultado e "repeated": true. Nada é enviado nem cobrado de novo; destinatários que não tinham saído são tentados outra vez.
Mesma chave, pedido diferente409 com o código email_idempotency_key_reused.
Mesma chave enquanto o primeiro envio ainda está em andamento409 com o código email_send_in_progress. Aguarde e repita.
Sem chave400 com o código email_idempotency_key_required.

Para a API, o pedido é o mesmo quando remetente, destinatários, reply_to, conteúdo (assunto, HTML, texto, modelo e variáveis), cabeçalhos, tags e anexos são iguais. Dentro de to, cc e bcc, a ordem dos endereços não importa; a ordem de reply_to e dos anexos importa.

Exemplo: ações em massa sobre leads

Em POST /leads/actions, a mesma chave com o mesmo pedido devolve o mesmo resultado sem refazer nada, e com outro pedido responde 409 com o código idempotency_key_reused. Sem a chave, a resposta é 400.


Did this page help you?