Docs
Páginas desta seção

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, 409 e 429 nã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çãoResposta
Sem a chave numa rota em que ela é obrigatória400 com o código idempotency_key_required. Nada é executado.
Chave com mais de 255 caracteres ou fora do ASCII visível400 com o código idempotency_key_invalid.
Mesma chave enquanto o primeiro pedido ainda roda409 com o código idempotency_in_progress e Retry-After: 1. Repita em instantes com a mesma chave.
Mesma chave com outro corpo422 com o código idempotency_key_reused.
A chave não pôde ser conferida503 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.

RotaChave
PATCH /v1/ads/objects/{metaId}/budgetObrigatória
PATCH /v1/ads/objects/{metaId}Obrigatória
POST /ads/drafts/{id}/publishObrigatória
POST /campaign-drafts/{channel}/{id}/launchObrigatória
POST /conversations/unofficial_whatsapp/{entryId}/number-transfer/linkObrigatória
POST /conversations/unofficial_whatsapp/{entryId}/number-transferObrigatória
POST /v1/ads/objects/{metaId}/activateObrigatória
POST /v1/ads/objects/{metaId}/copiesObrigatória
POST /v1/ads/publish-jobs/{id}/activateObrigatória
POST /v1/ads/publishObrigatória
POST /v1/ads/rulesObrigatória
POST /v1/call-campaignsObrigatória
POST /v1/carrier/campaigns/{id}/launchObrigatória
POST /v1/carrier/campaigns/{id}/testObrigatória
POST /v1/carrier/test-sendsObrigatória
POST /v1/conversations/whatsapp/{entryId}/formsObrigatória
POST /v1/conversations/{entryType}/{entryId}/messagesObrigatória
POST /v1/custom-fieldsOpcional
POST /v1/email/campaigns/{campaignId}/launchObrigatória
POST /v1/labelsOpcional
POST /v1/leads/upsertOpcional
POST /v1/leadsOpcional
POST /v1/media/generationsObrigatória
POST /v1/opportunitiesOpcional
POST /v1/pipelinesOpcional
POST /v1/reportsOpcional
POST /v1/unofficial-whatsapp/campaigns/{id}/quick-sendObrigatória
POST /v1/unofficial-whatsapp/campaigns/{id}/startObrigatória
POST /v1/unofficial-whatsapp/instancesOpcional
POST /v1/webhooksOpcional
POST /v1/whatsapp/campaigns/{id}/quick-sendObrigatória
POST /v1/whatsapp/campaigns/{id}/startObrigatória
PUT /v1/ads/accounts/{id}/spend-capObrigatória

Rotas com regras próprias

Estas rotas guardam a chave no próprio recurso e seguem as regras de cada uma.

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 /v1/email/outreach/conversationsCabeçalho Idempotency-KeySimGere 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 corpo ou cabeçalho Idempotency-Key (vale o do corpo quando os dois vêm)NãoDe 1 a 64 caracteres entre letras, números, _ e -.
POST /v1/ads/publishCabeçalho Idempotency-KeySimDe 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

  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.