Guias
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 das tabelas abaixo usam chave; nas demais, repetir um POST pode criar outro recurso.
Como a API repete uma resposta
- A chave vai no cabeçalho
Idempotency-Key, com 1 a 255 caracteres ASCII visíveis. - Ela vale por 24 horas dentro do mesmo workspace, para quem chama, o mesmo método e a mesma rota.
- Repetir o pedido com a mesma chave e o mesmo corpo devolve o status e o corpo da primeira resposta, com o cabeçalho
Idempotent-Replayed: true. Nada é feito de novo. - Respostas
5xx,409e429não ficam guardadas: repetir a mesma chave executa o pedido outra vez. - Nas rotas que enviam ou cobram, a API também confere o que já foi feito. Mesmo que a resposta se perca depois do envio, repetir a mesma chave nunca envia nem cobra duas vezes.
| Situação | Resposta |
|---|---|
| Sem a chave numa rota em que ela é obrigatória | 400 com o código idempotency_key_required. Nada é executado. |
| Chave com mais de 255 caracteres ou fora do ASCII visível | 400 com o código idempotency_key_invalid. |
| Mesma chave enquanto o primeiro pedido ainda roda | 409 com o código idempotency_in_progress e Retry-After: 1. Repita em instantes com a mesma chave. |
| Mesma chave com outro corpo | 422 com o código idempotency_key_reused. |
| A chave não pôde ser conferida | 503 com o código idempotency_unavailable. Nada é executado; repita com a mesma chave. |
Rotas com resposta repetida
Esta tabela é gerada a partir das próprias rotas da API. Nelas a chave vai no cabeçalho Idempotency-Key e segue as regras de Como a API repete uma resposta.
| Rota | Chave |
|---|---|
PATCH /v1/ads/objects/{metaId}/budget | Obrigatória |
PATCH /v1/ads/objects/{metaId} | Obrigatória |
POST /ads/drafts/{id}/publish | Obrigatória |
POST /campaign-drafts/{channel}/{id}/launch | Obrigatória |
POST /conversations/unofficial_whatsapp/{entryId}/number-transfer/link | Obrigatória |
POST /conversations/unofficial_whatsapp/{entryId}/number-transfer | Obrigatória |
POST /v1/ads/objects/{metaId}/activate | Obrigatória |
POST /v1/ads/objects/{metaId}/copies | Obrigatória |
POST /v1/ads/publish-jobs/{id}/activate | Obrigatória |
POST /v1/ads/publish | Obrigatória |
POST /v1/ads/rules | Obrigatória |
POST /v1/call-campaigns | Obrigatória |
POST /v1/carrier/campaigns/{id}/launch | Obrigatória |
POST /v1/carrier/campaigns/{id}/test | Obrigatória |
POST /v1/carrier/test-sends | Obrigatória |
POST /v1/conversations/whatsapp/{entryId}/forms | Obrigatória |
POST /v1/conversations/{entryType}/{entryId}/messages | Obrigatória |
POST /v1/custom-fields | Opcional |
POST /v1/email/campaigns/{campaignId}/launch | Obrigatória |
POST /v1/labels | Opcional |
POST /v1/leads/upsert | Opcional |
POST /v1/leads | Opcional |
POST /v1/media/generations | Obrigatória |
POST /v1/opportunities | Opcional |
POST /v1/pipelines | Opcional |
POST /v1/reports | Opcional |
POST /v1/unofficial-whatsapp/campaigns/{id}/quick-send | Obrigatória |
POST /v1/unofficial-whatsapp/campaigns/{id}/start | Obrigatória |
POST /v1/unofficial-whatsapp/instances | Opcional |
POST /v1/webhooks | Opcional |
POST /v1/whatsapp/campaigns/{id}/quick-send | Obrigatória |
POST /v1/whatsapp/campaigns/{id}/start | Obrigatória |
PUT /v1/ads/accounts/{id}/spend-cap | Obrigatória |
Rotas com regras próprias
Estas rotas guardam a chave no próprio recurso e seguem as regras de cada uma.
| 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 /v1/email/outreach/conversations | Cabeçalho Idempotency-Key | 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 ou cabeçalho Idempotency-Key (vale o do corpo quando os dois vêm) | Não | De 1 a 64 caracteres entre letras, números, _ e -. |
POST /v1/ads/publish | Cabeçalho Idempotency-Key | Sim | De 1 a 255 caracteres ASCII visíveis, única por workspace. Além da resposta repetida, a chave identifica a própria publicação: a mesma chave com o mesmo rascunho devolve a mesma publicação sem cobrar a taxa nem criar nada de novo, mesmo depois que a resposta guardada expira; com outro rascunho responde 422 com idempotency_key_reused. |
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.