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 | ip_not_allowed | A chave tem lista de IPs autorizados e a chamada veio de outro IP (ou de um IP que não pôde ser identificado). A checagem vem antes do escopo. | Adicione o IP de saída do seu servidor em Chaves de API › Editar IPs autorizados, ou esvazie a lista para aceitar qualquer IP. |
| 403 | forbidden_scope | A chave não tem o escopo exigido pela rota. | Gere uma chave com o escopo (os escopos de uma chave existente não mudam). |
| 403 | sandbox_forbidden | Chave sandbox numa rota fora da allow-list do sandbox. O ambiente é conferido antes do escopo. | Use uma chave de produção (bz_live_) nessa rota. Webhook para o sandbox: cadastre pelo painel, em Webhooks. |
| 429 | rate_limited | A Conta passou do limite de requisições da janela, ou do teto de envios. | Espere o Retry-After e use backoff. O limite é da Conta, somando todas as chaves. |
| 403 | account_deletion_in_progress | Workspace em somente leitura: a exclusão foi confirmada e fica 30 dias esperando começar (ou já está em andamento). Vale só para POST, PUT, PATCH e DELETE. | Leituras (GET) seguem funcionando, e o pedido de exportação (POST /v1/exports) também. Escritas ficam bloqueadas até o Administrador cancelar a exclusão em Configurações; depois que a exclusão começa, não há volta. |
| 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. Se continuar, mande ao suporte o x-request-id da resposta: toda resposta traz esse código, e com ele achamos a chamada. |
O rate limit é de 120 requisições a cada 10 segundos por Conta. Os envios (POST /v1/messages e o pedido de consentimento) têm ainda um teto de 60 envios a cada 10 segundos. 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 CRM do BotoZap. | Assine o BotoZap. |
| 403 ou 422 | plan_restricted | Recurso do BotoZap numa conta Free: agentes de IA, Agenda, réguas e automações (inclusive regras de mensagem e perguntas e menu do Direct do Instagram), relatório diário, transmissões, regras de comentário do Instagram e escrita no funil (Etapas e stage_id do contato). As rotas mais antigas (funil, transmissões e regras de comentário) respondem 422; as demais, 403. | Assine o BotoZap. Leituras (GET) 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. |
| 403 | account_paused_meta | Envio de uma Conta pausada: a Meta registrou duas violações de política em 14 dias, e o BotoZap parou os envios dela antes que a Meta restringisse o número. Recebimento e painel seguem. | Fale com o suporte do BotoZap para revisar e liberar. Repetir antes não adianta. |
| 402 | business_payment_required | Envio de um negócio pausado: a fatura do slot adicional dele venceu há mais de 7 dias. Só esse negócio para; os outros seguem. | Pague a fatura do slot (invoice_url em GET /api/v1/billing ou em Plano). Pagou, libera na hora. |
| 402 | free_number_cap | Envio por um número suspenso: o plano Free permite 1 número e este passou do teto. O número continua recebendo. | Assine o BotoZap ou desconecte o outro número. Libera na hora; repetir antes não adianta. |
| 402 | free_cap | Criação do segundo Cliente no Free (POST /api/v1/customers) ou envio por um Cliente suspenso: o plano Free permite 1 negócio, com conexão ou não. | Assine o BotoZap ou apague o Cliente que não usa. Libera na hora. |
| 402 | plan_required, slot_limit, billing_customer_required | Compra de slot adicional recusada: conta Free ou em teste grátis, 2 slots com fatura em aberto, ou conta sem cadastro de cobrança. | Assine o plano, pague uma das faturas em aberto ou fale com o suporte, nessa ordem. |
| 409 | slot_in_use | Cancelamento de um slot adicional ocupado por um negócio conectado. | Desconecte o negócio antes de cancelar o slot. |
| 429 | free_form_limit_reached | As 500 respostas 1:1 do mês no plano Free acabaram (painel, API e agentes de IA somam na mesma conta). | Assine o BotoZap. 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.
Conectar um segundo número real numa conta Free é recusado no fluxo de conexão (no painel ou no link de setup) com 402 free_number_cap. Números e Clientes que já existiam acima do teto ficam suspensos, sem exclusão: as leituras trazem plan_suspended: true e o envio responde free_number_cap ou free_cap. O convite de um segundo membro é recusado no próprio painel, sem código HTTP; membros além do primeiro ficam suspensos até a assinatura.
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). | 4 |
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). | 5 |
conversations:write | Gerenciar conversas | Encerrar, reabrir e excluir conversas e atribuir responsáveis (PATCH e DELETE /v1/conversations/:id e assignments). A exclusão apaga as mensagens e a mídia da conversa e não tem volta. | 5 |
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; ligar modelos prontos, que submetem o template do modelo à Meta; programar e controlar Disparos (/v1/journeys e /v1/journey-runs). | 7 |
journeys:read | Ler Réguas | Consultar Réguas e Disparos (GET /v1/journeys e /v1/journey-runs). | 5 |
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 |
|---|
message-rules:read | Ler regras de mensagem | Listar e consultar Regras de mensagem do Instagram. | 3 |
message-rules:write | Gerenciar regras de mensagem | Criar, editar, pausar e excluir Regras de mensagem do Instagram. | 3 |
messenger-profile:read | Ler perfil de mensagens | Consultar perguntas e menu do Instagram. | 1 |
messenger-profile:write | Gerenciar perfil de mensagens | Salvar, remover e reaplicar perguntas e menu do Instagram. | 3 |
comment-rules:read | Ler regras de comentário | Listar e consultar regras de comentário do Instagram. | 3 |
comment-rules:write | Gerenciar regras de comentário | Criar, editar, ativar e desativar regras de comentário do Instagram. | 3 |
templates:read | Ler templates | Listar e consultar templates (GET /v1/templates). | 2 |
templates:write | Gerenciar templates | Criar templates (POST /v1/templates). | 4 |
numbers:read | Ler números e canais | Listar números e canais, consultar saúde e conexão do Instagram. | 12 |
numbers:write | Gerenciar números e canais | Editar e remover números; refazer a assinatura e desconectar o Instagram. | 15 |
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). | 5 |
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) e consultar o registro de atividades (GET /v1/team_events, só de Administrador). | 2 |
logs:read | Ler logs | Consultar logs de API (GET /v1/api_logs). | 2 |
Plano e cobrança
| Escopo | Permissão | O que libera | Rotas |
|---|
billing:read | Ler plano e cobrança | Consultar o plano, os negócios incluídos e os slots adicionais com vencimento e fatura (GET /v1/billing). | 1 |
billing:write | Gerenciar slots adicionais | Comprar e cancelar slots adicionais de R$ 47/mês (POST e DELETE /v1/billing/slots). Comprar gera cobrança. | 2 |
Exportação de dados
| Escopo | Permissão | O que libera | Rotas |
|---|
exports:read | Ler exportações de dados | Consultar o histórico e o status das exportações e obter o link de download (GET /v1/exports). | 2 |
exports:write | Pedir exportações de dados | Pedir a exportação completa da Conta ou de um Cliente: contatos, conversas, mensagens e registro de envio (POST /v1/exports). | 1 |
Agente de IA
| Escopo | Permissão | O que libera | Rotas |
|---|
agents:read | Ler agentes | Consultar agentes, execuções e pendências. | 75 |
agents:write | Gerenciar agentes | Configurar agentes e controlar atendimento. | 84 |