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
| Rota | Onde vai a chave | Obrigatória | Regras |
|---|---|---|---|
POST /email/transactional/messages | Campo idempotency_key do corpo ou cabeçalho Idempotency-Key (vale o do corpo quando os dois vêm) | Sim | De 1 a 256 caracteres ASCII imprimíveis. Única por workspace, sem prazo de expiração. |
POST /email/outreach/conversations | Campo idempotency_key do corpo | Sim | Gere uma vez por e-mail composto. |
POST /leads/actions | Cabeçalho Idempotency-Key | Sim | Até 128 caracteres. |
POST /google-sheets/{id}/rows | Cabeçalho Idempotency-Key | Sim | Única por usuário. |
POST /user/invoices | Campo idempotencyKey do corpo | Não | De 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
- Gere a chave antes da primeira tentativa e guarde-a junto com o registro que originou o pedido, por exemplo
recibo-pedido-1234ou um UUID. - Envie o pedido com a chave.
- Se a conexão cair, a chamada estourar o tempo ou a resposta for
502ou503, repita o mesmo pedido com a mesma chave. - 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ção | Resposta |
|---|---|
| Mesma chave, mesmo pedido | 200 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 diferente | 409 com o código email_idempotency_key_reused. |
| Mesma chave enquanto o primeiro envio ainda está em andamento | 409 com o código email_send_in_progress. Aguarde e repita. |
| Sem chave | 400 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.
Updated 17 days ago