Erros

Todo erro responde com o status HTTP correspondente e o mesmo corpo:

{
  "error": "ERR_ESCOPO_INSUFICIENTE",
  "message": "O app não tem o escopo crm:escrever."
}

error é estável: é ele que o seu código deve tratar.
message é um texto em português para pessoas. Pode mudar sem aviso; não faça parse dele. Em ERR_VALIDACAO, ele vem no formato campo: problema.
O formato vale também para POST /oauth/token (não é o formato de erro do RFC 6749).

Tentar de novo?

Situação	O que fazer
`429`	Espere o tempo do cabeçalho `Retry-After` (quando houver) e tente de novo
`409 ERR_REQUISICAO_EM_ANDAMENTO`, `409 ERR_WHATSAPP_DESCONECTADO`, `409 ERR_CONFLITO`	Tente de novo mais tarde, com a mesma `Idempotency-Key`
`5xx` e falha de rede	Tente de novo com espera crescente, com a mesma `Idempotency-Key`
`401 ERR_TOKEN_INVALIDO`	Renove o token uma vez e repita. Se falhar de novo, a instalação ou a chave perdeu a validade
Outros `4xx`	Não tente de novo sem corrigir a requisição. São resultados finais

Código	HTTP	Quando
`ERR_TOKEN_INVALIDO`	401	Token ausente, expirado, com assinatura inválida, ou chave de integração revogada, expirada ou inexistente
`ERR_TOKEN_REVOGADO`	401	Token de usuário (tela em iframe) depois de logout ou de o usuário ser inativado
`ERR_ESCOPO_INSUFICIENTE`	403	O endpoint exige um escopo que o app (ou a chave) não tem
`ERR_APP_NAO_HABILITADO`	403	A empresa desinstalou o app, o plano não inclui apps de parceiro ou o app foi suspenso
`ERR_PLANO_SEM_RECURSO`	403	O plano da empresa não inclui o recurso (ex.: chaves de integração)
`ERR_ASSINATURA_VENCIDA` / `ERR_ASSINATURA_BLOQUEADA`	403	Escrita com a assinatura da empresa vencida ou bloqueada. Leituras continuam funcionando
`ERR_OPERACAO_RECUSADA`	403	Uma regra de negócio do Botzetta recusou a escrita. Não é problema de token nem de escopo
`ERR_EMPRESA_DIVERGENTE`	400	`X-Botzetta-Empresa` diferente da empresa do token ou da chave

Código	HTTP	Quando
`ERR_CREDENCIAIS_INVALIDAS`	401	`client_id` ou `client_secret` inválidos ou revogados
`ERR_OAUTH_PARAMETRO`	400	Parâmetro ausente ou inválido no fluxo OAuth
`ERR_OAUTH_CODIGO_INVALIDO`	400	Código expirado, já usado, ou PKCE/`redirect_uri` diferentes da autorização
`ERR_OAUTH_REFRESH_INVALIDO`	400	Refresh token expirado, revogado ou já usado
`ERR_GRANT_NAO_PERMITIDO`	400	`grant_type` não permitido para este app (parceiro usa `authorization_code` e `refresh_token`)
`ERR_LIMITE_APP_PRIVADO`	403	App ainda não liberado pela Botzetta já está instalado em 5 empresas
`ERR_APP_INDISPONIVEL`	404	A versão ativa pede escopo de risco alto ainda não aprovado; só a sandbox instala

Código	HTTP	Quando
`ERR_VALIDACAO`	400	Corpo ou parâmetros inválidos (`message` = `campo: problema`). Também cursor de paginação adulterado
`ERR_NAO_ENCONTRADO`	404	Recurso inexistente ou de outra empresa. A API nunca diferencia os dois casos
`ERR_IDEMPOTENCY_KEY_OBRIGATORIA`	400	`POST` que cria registro ou envia mensagem sem `Idempotency-Key`
`ERR_IDEMPOTENCY_KEY_REUTILIZADA`	422	A mesma chave foi usada com outro corpo ou em outra rota
`ERR_REQUISICAO_EM_ANDAMENTO`	409	A mesma chave ainda está sendo processada
`ERR_CONFLITO`	409	O estado do registro mudou e a escrita não pôde ser aplicada agora
`ERR_LIMITE_REQUISICOES`	429	Limite de requisições por minuto excedido. Veja Limites

Código	HTTP	Quando
`ERR_CONTATO_EXISTENTE`	409	`POST /pessoas` com WhatsApp que já é de outra pessoa da empresa. A API nunca unifica cadastros
`ERR_WHATSAPP_DESCONECTADO`	409	A conexão de WhatsApp está desconectada (pode tentar de novo depois)
`ERR_DESTINO_SEM_WHATSAPP`	422	A pessoa não tem contato de WhatsApp
`ERR_DESTINO_INVALIDO`	422	Número de destino inválido
`ERR_DESTINO_OPT_OUT`	422	A pessoa (ou o número) pediu para não receber mensagens. Trate como resultado final
`ERR_TEMPLATE_INVALIDO`	422	Template inexistente
`ERR_CANAL_NAO_SUPORTADO`	422	A conexão não suporta envio pela API (ex.: conexão pela API oficial da Meta)
`ERR_MIDIA_MULTIPLA_NAO_SUPORTADA`	422	Mais de uma mídia na mesma mensagem
`ERR_LIMITE_ENVIO_AVULSO`	429	Teto diário de envios para número avulso atingido (com `Retry-After` até a meia-noite)
`ERR_EVENTO_NAO_DECLARADO`	422	Evento de tempo real não declarado no manifesto do app

Código	HTTP	Quando
`ERR_INTERNO`	500	Erro inesperado. Tente de novo com espera; se persistir, fale com o suporte informando o `X-Request-Id`
`ERR_PLATAFORMA_NAO_CONFIGURADA`	503	Plataforma temporariamente indisponível

Os códigos de cada endpoint aparecem também na seção de respostas da referência.