Erros e escopos

O que cada código de erro da API /v1 significa, qual status HTTP acompanha e o que fazer. No fim, o catálogo completo de escopos das chaves.

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:

HTTPCódigoQuandoO que fazer
401unauthorizedChave ausente, com prefixo desconhecido, revogada ou expirada.Confira o header e a chave no painel. Chave expirada não volta: gere outra.
403ip_not_allowedA 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.
403forbidden_scopeA chave não tem o escopo exigido pela rota.Gere uma chave com o escopo (os escopos de uma chave existente não mudam).
403sandbox_forbiddenChave 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.
429rate_limitedA 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.
403account_deletion_in_progressWorkspace 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.
403console_requiredA Conta não tem acesso ativo ao produto (assinatura cancelada ou ausente).Um Administrador da Conta deve regularizar a assinatura em Plano.
500internal_errorFalha 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

HTTPCódigoQuandoO que fazer
400invalid_jsonO corpo não é JSON válido (ou passou do tamanho aceito).Corrija o corpo e envie Content-Type: application/json.
404not_foundO 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.
422invalid_requestCampo 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.
409conflict e variantesEstado 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

HTTPCódigoQuandoO que fazer
403feature_unavailableOportunidades, demandas e Radar exigem o CRM do BotoZap.Assine o BotoZap.
403 ou 422plan_restrictedRecurso 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.
402quota_exceededEnvio de template além da cota do plano ou com cobrança pendente.Confira Plano e uso; regularize ou espere a renovação.
403account_paused_metaEnvio 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.
402business_payment_requiredEnvio 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.
402free_number_capEnvio 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.
402free_capCriaçã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.
402plan_required, slot_limit, billing_customer_requiredCompra 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.
409slot_in_useCancelamento de um slot adicional ocupado por um negócio conectado.Desconecte o negócio antes de cancelar o slot.
429free_form_limit_reachedAs 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.
503billing_unavailableNã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

EscopoPermissãoO que liberaRotas
messages:sendEnviar mensagensDisparar mensagens pela API (POST /v1/messages).4
messages:readLer mensagensConsultar mensagens (GET /v1/messages).2
events:readLer eventosRecuperar Eventos duráveis por cursor (GET /v1/events).1
media:readLer mídiaConsultar mídia recebida (GET /v1/media/:id).2
media:writeEnviar arquivos de mídiaGuardar no BotoZap imagens, vídeos, áudios e documentos a partir de um link, para usar nas mensagens (POST /v1/media).1

Contatos e atendimento

EscopoPermissãoO que liberaRotas
conversations:readLer conversasListar e consultar conversas (GET /v1/conversations).5
conversations:writeGerenciar conversasEncerrar, 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:readLer contatosListar e consultar contatos (GET /v1/contacts).5
contacts:writeGerenciar contatosCriar, editar e apagar contatos (POST/PATCH/DELETE /v1/contacts).11
saved_replies:readLer respostas rápidasConsultar as respostas rápidas compartilhadas da Conta.2
saved_replies:writeGerenciar respostas rápidasCriar, editar e apagar as respostas rápidas compartilhadas da Conta.3
inbox:readConsultar notas internas, retornos e organização do InboxConsultar notas internas, retornos e organização do Inbox da Conta.1
inbox:writeGerenciar notas internas, retornos e organização do InboxGerenciar notas internas, retornos e organização do Inbox da Conta.1

CRM, Agenda e Réguas

EscopoPermissãoO que liberaRotas
calendar:readLer calendáriosConsultar conexões e sincronização do Google Calendar da Conta.3
calendar:writeGerenciar calendáriosSelecionar calendários, desconectar e resolver falhas de sincronização da Conta.5
appointments:readLer agendamentosConsultar compromissos, disponibilidade, serviços, jornadas e exceções da Agenda (GET /v1/appointments/*).7
appointments:writeGerenciar agendamentosCriar, editar e apagar compromissos e configurar serviços, jornadas e exceções da Agenda (POST/PATCH/DELETE /v1/appointments/*).10
journeys:writeGerenciar RéguasCriar, 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:readLer RéguasConsultar Réguas e Disparos (GET /v1/journeys e /v1/journey-runs).5
crm:readConsultar CRM e RadarConsultar oportunidades, demandas, pendências e critérios do Radar da Conta.10
crm:writeGerenciar oportunidades e demandasGerenciar oportunidades e demandas e configurar critérios do Radar da Conta.9

Canais e templates

EscopoPermissãoO que liberaRotas
message-rules:readLer regras de mensagemListar e consultar Regras de mensagem do Instagram.3
message-rules:writeGerenciar regras de mensagemCriar, editar, pausar e excluir Regras de mensagem do Instagram.3
messenger-profile:readLer perfil de mensagensConsultar perguntas e menu do Instagram.1
messenger-profile:writeGerenciar perfil de mensagensSalvar, remover e reaplicar perguntas e menu do Instagram.3
comment-rules:readLer regras de comentárioListar e consultar regras de comentário do Instagram.3
comment-rules:writeGerenciar regras de comentárioCriar, editar, ativar e desativar regras de comentário do Instagram.3
templates:readLer templatesListar e consultar templates (GET /v1/templates).2
templates:writeGerenciar templatesCriar templates (POST /v1/templates).4
numbers:readLer números e canaisListar números e canais, consultar saúde e conexão do Instagram.12
numbers:writeGerenciar números e canaisEditar e remover números; refazer a assinatura e desconectar o Instagram.15

Transmissões

EscopoPermissãoO que liberaRotas
broadcasts:readLer transmissõesListar e consultar broadcasts e destinatários (GET /v1/broadcasts).3
broadcasts:writeGerenciar transmissõesCriar, agendar, enviar e cancelar broadcasts (POST /v1/broadcasts).7

Clientes, equipe e integração

EscopoPermissãoO que liberaRotas
webhooks:readLer webhooksListar webhooks e entregas (GET /v1/webhooks, /webhook_deliveries).3
webhooks:writeGerenciar webhooksCriar, editar, testar e excluir webhooks (POST/PATCH/DELETE).5
customers:readLer clientesListar e consultar clientes e setup links (GET /v1/customers).4
customers:writeGerenciar clientesCriar, editar e apagar clientes e setup links.5
team:readLer equipeListar membros do workspace (GET /v1/users) e consultar o registro de atividades (GET /v1/team_events, só de Administrador).2
logs:readLer logsConsultar logs de API (GET /v1/api_logs).2

Plano e cobrança

EscopoPermissãoO que liberaRotas
billing:readLer plano e cobrançaConsultar o plano, os negócios incluídos e os slots adicionais com vencimento e fatura (GET /v1/billing).1
billing:writeGerenciar slots adicionaisComprar e cancelar slots adicionais de R$ 47/mês (POST e DELETE /v1/billing/slots). Comprar gera cobrança.2

Exportação de dados

EscopoPermissãoO que liberaRotas
exports:readLer exportações de dadosConsultar o histórico e o status das exportações e obter o link de download (GET /v1/exports).2
exports:writePedir exportações de dadosPedir a exportação completa da Conta ou de um Cliente: contatos, conversas, mensagens e registro de envio (POST /v1/exports).1

Agente de IA

EscopoPermissãoO que liberaRotas
agents:readLer agentesConsultar agentes, execuções e pendências.75
agents:writeGerenciar agentesConfigurar agentes e controlar atendimento.84