BotoZap: WhatsApp oficial conectado em minutos

Todo erro da API /v1 vem no mesmo envelope. Decida pelo code, que é estável; message é texto em português para gente ler e pode mudar.

{
  "error": {
    "code": "sandbox_forbidden",
    "message": "Chave de ambiente sandbox não pode acessar esta rota. ..."
  }
}

Erros de qualquer rota

Antes do código de cada rota, toda requisição passa pelas mesmas checagens, nesta ordem. A primeira que falhar responde:

HTTP	Código	Quando	O que fazer
401	`unauthorized`	Chave ausente, com prefixo desconhecido, revogada ou expirada.	Confira o header e a chave no painel. Chave expirada não volta: gere outra.
403	`forbidden_scope`	A chave não tem o escopo exigido pela rota.	Gere uma chave com o escopo (não dá para editar os escopos de uma chave existente).
403	`sandbox_forbidden`	Chave sandbox numa rota fora da allow-list do sandbox.	Use uma chave de produção (bz_live_) nessa rota.
429	`rate_limited`	A Conta passou do limite de requisições da janela.	Espere o Retry-After e use backoff. O limite é da Conta, somando todas as chaves.
403	`account_deletion_in_progress`	Conta em processo de exclusão; vale só para POST, PUT, PATCH e DELETE.	Leituras (GET) seguem funcionando; escritas ficam bloqueadas enquanto a exclusão estiver ativa.
403	`console_required`	A Conta não tem acesso ativo ao produto (assinatura cancelada ou ausente).	Um Administrador da Conta deve regularizar a assinatura em Plano.
500	`internal_error`	Falha interna, inclusive ao consultar o acesso da Conta ou o ambiente da chave. Nunca vira sucesso nem lista vazia.	Tente de novo com backoff. Numa escrita sem resposta clara, releia o recurso antes de repetir.

O rate limit é de 120 requisições a cada 10 segundos por Conta, e o 429 traz X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e Retry-After. Veja Autenticação para chaves, ambientes e expiração.

Erros comuns nas rotas

HTTP	Código	Quando	O que fazer
400	`invalid_json`	O corpo não é JSON válido (ou passou do tamanho aceito).	Corrija o corpo e envie Content-Type: application/json.
404	`not_found`	O recurso não existe, é de outra Conta ou de outro ambiente. A API não distingue os três casos.	Confira o id e o ambiente da chave.
422	`invalid_request`	Campo ausente ou inválido. Muitas rotas usam um código mais específico (missing_name, invalid_status, invalid_customer…).	Leia message: ela diz qual campo corrigir. Não repita sem corrigir.
409	`conflict e variantes`	Estado mudou no meio do caminho: versão desatualizada, atribuição disputada, recurso em uso.	Releia o recurso e decida de novo. Não repita cegamente.

Os códigos específicos de cada recurso aparecem na referência e nos guias.

Plano e cobrança

HTTP	Código	Quando	O que fazer
403	`feature_unavailable`	Oportunidades, demandas e Radar exigem o funil dos planos pagos.	Assine o Starter ou o Pro.
422	`plan_restricted`	Recurso de plano pago: transmissões, criar/editar/reordenar Etapas do funil e mudar a etapa (stage_id) de um contato.	Assine o Starter ou o Pro. Leitura das Etapas e respostas 1:1 na janela de 24h continuam liberadas.
402	`quota_exceeded`	Envio de template além da cota do plano ou com cobrança pendente.	Confira Plano e uso; regularize ou espere a renovação.
429	`free_form_limit_reached`	Respostas 1:1 do plano Free esgotadas no mês.	Assine um plano pago. Não é rate limit: repetir não adianta.
503	`billing_unavailable`	Não foi possível consultar a cobrança. O envio foi recusado antes da Meta.	Transitório: tente de novo com backoff.

trial_expired está reservado no contrato, mas nenhuma rota /v1 o devolve hoje: um trial vencido volta às regras do Free e recebe plan_restricted. Trate os dois da mesma forma.

Erros de envio

Nas recusas de POST /api/v1/messages, inclusive as das checagens acima, o objeto error ganha campos para decidir o próximo passo sem adivinhar:

{
  "error": {
    "code": "outside_window",
    "message": "...",
    "outcome": "rejected",
    "retry": "after_correction",
    "next_step": "Use um Template aprovado ou aguarde uma nova mensagem do Contato..."
  }
}

outcome: rejected (recusado antes da Meta, nada saiu), accepted ou unknown (pode ter saído).
retry: after_correction (corrija antes de repetir), backoff (transitório), reconcile_first (consulte a mensagem e os Eventos antes de repetir, para não duplicar) ou unknown.
next_step: o que fazer, em português.
meta_code: o código de erro da Meta, quando ela respondeu.

Os códigos de envio (janela de 24h, número desconectado, template) estão em Enviar mensagens.

Catálogo de escopos

Cada chave recebe uma lista de escopos na criação, no formato recurso:ação. Leitura (:read) não inclui escrita, e escrita (:write) não inclui leitura: marque os dois quando a integração precisar. A coluna Rotas conta as rotas /v1 que exigem o escopo, incluindo as do Agente de IA.

Mensagens, eventos e mídia

Escopo	Permissão	O que libera	Rotas
`messages:send`	Enviar mensagens	Disparar mensagens pela API (POST /v1/messages).	1
`messages:read`	Ler mensagens	Consultar mensagens (GET /v1/messages).	2
`events:read`	Ler eventos	Recuperar Eventos duráveis por cursor (GET /v1/events).	1
`media:read`	Ler mídia	Consultar mídia recebida (GET /v1/media/:id).	2
`media:write`	Enviar arquivos de mídia	Guardar no BotoZap imagens, vídeos, áudios e documentos a partir de um link, para usar nas mensagens (POST /v1/media).	1

Contatos e atendimento

Escopo	Permissão	O que libera	Rotas
`conversations:read`	Ler conversas	Listar e consultar conversas (GET /v1/conversations).	4
`conversations:write`	Gerenciar conversas	Encerrar conversas e atribuir responsáveis (PATCH /v1/conversations/:id e assignments).	3
`contacts:read`	Ler contatos	Listar e consultar contatos (GET /v1/contacts).	5
`contacts:write`	Gerenciar contatos	Criar, editar e apagar contatos (POST/PATCH/DELETE /v1/contacts).	11
`saved_replies:read`	Ler respostas rápidas	Consultar as respostas rápidas compartilhadas da Conta.	2
`saved_replies:write`	Gerenciar respostas rápidas	Criar, editar e apagar as respostas rápidas compartilhadas da Conta.	3
`inbox:read`	Consultar notas internas, retornos e organização do Inbox	Consultar notas internas, retornos e organização do Inbox da Conta.	1
`inbox:write`	Gerenciar notas internas, retornos e organização do Inbox	Gerenciar notas internas, retornos e organização do Inbox da Conta.	1

CRM, Agenda e Réguas

Escopo	Permissão	O que libera	Rotas
`calendar:read`	Ler calendários	Consultar conexões e sincronização do Google Calendar da Conta.	3
`calendar:write`	Gerenciar calendários	Selecionar calendários, desconectar e resolver falhas de sincronização da Conta.	5
`appointments:read`	Ler agendamentos	Consultar compromissos, disponibilidade, serviços, jornadas e exceções da Agenda (GET /v1/appointments/*).	7
`appointments:write`	Gerenciar agendamentos	Criar, editar e apagar compromissos e configurar serviços, jornadas e exceções da Agenda (POST/PATCH/DELETE /v1/appointments/*).	10
`journeys:write`	Gerenciar Réguas	Criar, editar, pausar e arquivar Réguas; programar e controlar Disparos (/v1/journeys e /v1/journey-runs).	6
`journeys:read`	Ler Réguas	Consultar Réguas e Disparos (GET /v1/journeys e /v1/journey-runs).	4
`crm:read`	Consultar CRM e Radar	Consultar oportunidades, demandas, pendências e critérios do Radar da Conta.	10
`crm:write`	Gerenciar oportunidades e demandas	Gerenciar oportunidades e demandas e configurar critérios do Radar da Conta.	9

Canais e templates

Escopo	Permissão	O que libera	Rotas
`templates:read`	Ler templates	Listar e consultar templates (GET /v1/templates).	2
`templates:write`	Gerenciar templates	Criar templates (POST /v1/templates).	1
`numbers:read`	Ler números	Listar números e checar saúde (GET /v1/phone_numbers).	5
`numbers:write`	Gerenciar números	Editar e remover números (PATCH/DELETE /v1/phone_numbers/:id).	2

Transmissões

Escopo	Permissão	O que libera	Rotas
`broadcasts:read`	Ler transmissões	Listar e consultar broadcasts e destinatários (GET /v1/broadcasts).	3
`broadcasts:write`	Gerenciar transmissões	Criar, agendar, enviar e cancelar broadcasts (POST /v1/broadcasts).	7

Clientes, equipe e integração

Escopo	Permissão	O que libera	Rotas
`webhooks:read`	Ler webhooks	Listar webhooks e entregas (GET /v1/webhooks, /webhook_deliveries).	3
`webhooks:write`	Gerenciar webhooks	Criar, editar, testar e excluir webhooks (POST/PATCH/DELETE).	4
`customers:read`	Ler clientes	Listar e consultar clientes e setup links (GET /v1/customers).	4
`customers:write`	Gerenciar clientes	Criar, editar e apagar clientes e setup links.	5
`team:read`	Ler equipe	Listar membros do workspace (GET /v1/users).	1
`logs:read`	Ler logs	Consultar logs de API (GET /v1/api_logs).	1

Agente de IA

Escopo	Permissão	O que libera	Rotas
`agents:read`	Ler agentes	Consultar agentes, execuções e pendências.	71
`agents:write`	Gerenciar agentes	Configurar agentes e controlar atendimento.	83

Erros e escopos