Códigos de Erro

19. Códigos de Erro#

Formato unificado de resposta#

Todos os erros seguem o mesmo envelope JSON, com error_code estável para handling tipado e trace_id para casamento exato com o log do backend:

json
{
  "error_code": "INSTANCE_NOT_CONNECTED",
  "message": "instance is not connected (status: DISCONNECTED)",
  "trace_id": "2a62142c-f55f-4db4-8c7b-060018e3ef48",
  "error":   "instance is not connected (status: DISCONNECTED)"
}
Campo Descricao
error_code Código estável em SCREAMING_SNAKE_CASE. Use isso pra lógica condicional no cliente.
message Mensagem legivel para humanos.
trace_id UUID que identifica unicamente o request. Também disponível no header de resposta X-Trace-ID. Use para correlacionar com a consulta de logs superadmin filtrada por trace_id.
error Campo legacy, identico a message. Mantido por uma release para integradores antigos. Migre para message.

O header X-Trace-ID está exposto via CORS e pode ser lido pelo navegador (error.response.headers['x-trace-id']).

Códigos HTTP#

Código error_code padrão Descricao
400 BAD_REQUEST Corpo inválido, campos faltando ou inválidos
401 UNAUTHORIZED / TOKEN_INVALID Token ausente, expirado ou inválido
403 FORBIDDEN / COMPANY_SUSPENDED / INSUFFICIENT_PERMISSIONS Sem permissão, empresa suspensa
404 NOT_FOUND / INSTANCE_NOT_FOUND / MESSAGE_NOT_FOUND / WEBHOOK_NOT_FOUND Recurso não encontrado
409 CONFLICT / DUPLICATE_INSTANCE_NAME / INSTANCE_NOT_CONNECTED Estado conflitante
422 UNPROCESSABLE_ENTITY Dados válidos mas não processaveis
429 RATE_LIMITED / ACCOUNT_LOCKED Rate limit excedido (RATE_LIMITED) ou conta travada por brute-force (ACCOUNT_LOCKED). Verifique os headers Retry-After e X-RateLimit-*
500 INTERNAL_ERROR Erro interno do servidor
501 NOT_IMPLEMENTED Operação válida mas ainda não suportada pela capacidade atual da instância. A requisição está correta; só não há suporte nessa superfície ainda
503 SERVICE_UNAVAILABLE Serviço degradado (MySQL/Redis/S3, lookup de empresa no JWT)

Códigos de erro estáveis#

A lista canonica vive em whats-api/internal/api/error_codes.go (códigos auth/role de middleware em whats-api/internal/middleware/error_response.go). Lista completa:

error_code Quando ocorre
Genericos (fallback por status HTTP)
BAD_REQUEST Fallback de 400 quando nenhum código explicito foi setado
UNAUTHORIZED Fallback de 401 — autenticação ausente
FORBIDDEN Fallback de 403 — sem permissão
NOT_FOUND Fallback de 404 — recurso não encontrado
CONFLICT Fallback de 409 — estado conflitante
UNPROCESSABLE_ENTITY Fallback de 422 — dados válidos mas não processaveis
RATE_LIMITED Fallback de 429 — rate limit excedido
SERVICE_UNAVAILABLE Fallback de 503 — serviço degradado
INTERNAL_ERROR Fallback de 500+ — erro interno
Auth / sessão
INVALID_CREDENTIALS Email ou senha errados no login
ACCOUNT_LOCKED Mais de 5 tentativas falhas em 15min
TOKEN_EXPIRED JWT expirado
TOKEN_INVALID JWT malformado, expirado ou não encontrado / API key inválida
CSRF_INVALID Token CSRF ausente ou não bate em request unsafe do navegador
REFRESH_FAILED Refresh token ausente ou já consumido
REGISTRATION_FAILED Falha interna durante o cadastro
EMAIL_ALREADY_REGISTERED Email já em uso no register
RESET_TOKEN_INVALID Token de reset não encontrado ou já usado
RESET_TOKEN_EXPIRED Token de reset passou da janela de 30min (PASSWORD_RESET_TTL)
PASSWORD_CHANGED JWT emitido antes da senha ser alterada. O refresh-token também já foi revogado — cliente descarta o token e vai pro /login
OAUTH_PROVIDER_INVALID Provider social desconhecido
OAUTH_PROVIDER_DISABLED Provider social desabilitado ou sem credenciais
OAUTH_STATE_INVALID State OAuth ausente, expirado ou inválido
OAUTH_EMAIL_UNVERIFIED Provider não confirmou email verificado
OAUTH_PENDING_INVALID Token de conclusao de cadastro social inválido ou expirado
OAUTH_UPSTREAM_FAILED Falha ao conversar com Google/GitHub
Roles / permissão (middleware)
INSUFFICIENT_PERMISSIONS Role autenticada sem permissão para a rota
SUPERADMIN_REQUIRED Rota superadmin acessada sem is_superadmin
Verificação de email
EMAIL_NOT_VERIFIED Ação gated exige email confirmado (criar instância/token/webhook)
EMAIL_ALREADY_VERIFIED Email já confirmado
EMAIL_VERIFICATION_CODE_INVALID Código de 6 digitos errado
EMAIL_VERIFICATION_CODE_EXPIRED Código de verificação expirado
EMAIL_VERIFICATION_RESEND_COOLDOWN Reenvio de código solicitado dentro do cooldown
EMAIL_VERIFICATION_MAX_ATTEMPTS Excedeu o número de tentativas de código
Tenancy / plano
COMPANY_SUSPENDED Empresa está com status != active
PLAN_LIMIT_REACHED Limite do plano atingido
Instância
INSTANCE_NOT_FOUND Instância não existe ou não pertence a empresa
INSTANCE_NOT_CONNECTED Tentativa de send em instância que não está CONNECTED
PROVIDER_MIGRATION_NOT_NEEDED migrate-provider: a instância já usa o provider pedido (409)
PROVIDER_MIGRATION_UNSUPPORTED migrate-provider: só whatsmeow → wwebjs é suportado (400)
PROVIDER_MIGRATION_BUSY migrate-provider: instância conectando/pareando ou alterada durante a migração (409)
PROVIDER_MIGRATION_LOGOUT_TIMEOUT migrate-provider: o aparelho atual não confirmou o logout; nada foi trocado (504)
INSTANCE_BANNED Instância banida pelo WhatsApp
INSTANCE_HARD_PAUSED Throttler em hard pause após rate limits repetidos
DUPLICATE_INSTANCE_NAME Nome de instância já em uso na empresa
INVALID_INSTANCE_NAME Nome de instância inválido (3-80 chars)
INVALID_INSTANCE_TRANSITION Transicao inválida (ex: connect em CREATED)
META_CREDENTIALS_INVALID Credenciais da WABA (token/phone_number_id) rejeitadas pela Graph API — token inválido/expirado ou sem permissão. Reautorize. Distinto de META_REQUEST_INVALID
META_REQUEST_INVALID Rejeição de validação da Graph (NÃO é credencial): ex. rodapé > 60 chars, variáveis demais para o tamanho, destinatário não suportado. A message carrega a razão específica da Meta (error_user_msg) — corrija a requisição, não o token
META_RATE_LIMITED Graph API limitando a taxa (429 / code 4 / 80007 / 130429 …) — aguarde e tente novamente
OFFICIAL_CHANNEL_NOT_IN_PLAN Criação de conexão oficial (whatsapp_official) não incluída no plano da empresa
OUTSIDE_SERVICE_WINDOW Envio free-form no canal oficial fora da janela de 24h — use um template aprovado
Mensageria
INVALID_JSON Corpo não e JSON válido
MISSING_FIELD Campo obrigatório ausente
INVALID_PHONE Número brasileiro com formato errado
INVALID_RECIPIENT Formato de destinatário inválido
RECIPIENT_NOT_ON_WHATSAPP Número bem-formado mas NÃO é um usuário WhatsApp. Para números BR, só é emitido depois de o worker consultar TAMBÉM a variante irmã do 9º dígito (55DD9XXXXXXXX ↔ 55DDXXXXXXXX) — ver seção 20. Retornado síncrono (422) num envio a um número já confirmado inválido (cache do worker); também aparece como error_code numa mensagem failed. Distinto de INVALID_RECIPIENT (número mal-formado)
CONTACT_NOT_ON_WHATSAPP PUT .../contacts/{phone}: o número (e a variante do 9º dígito) não tem WhatsApp (404)
CONTACT_SAVE_NOT_SUPPORTED PUT .../contacts/{phone}: o provider da instância não grava na agenda; só o wwebjs grava (501)
CONTACT_SAVE_FAILED PUT .../contacts/{phone}: a página do WhatsApp Web não concluiu o salvamento (502)
CONTACT_NOT_SAVED DELETE .../contacts/{phone}: o número pedido não está salvo na agenda; nada é apagado. saved_as traz a outra forma do 9º dígito quando ela está salva (404)
CONTACT_DELETE_NOT_SUPPORTED DELETE .../contacts/{phone}: o provider da instância não grava na agenda; só o wwebjs grava (501)
CONTACT_DELETE_FAILED DELETE .../contacts/{phone}: o WhatsApp Web não confirmou que apagou (502)
CONTACT_CHECK_FAILED POST .../contacts/check (wwebjs): a consulta ao WhatsApp falhou; nenhuma resposta parcial (502)
INVALID_STICKER_ID Rotas de figurinha e messages/sticker com sticker_id: id malformado (400)
STICKER_NOT_FOUND A figurinha não está em Recentes/Favoritas da conta (404; no envio, em message.delivery_failed)
STICKER_NOT_SUPPORTED Figurinhas salvas só no wwebjs (501)
STICKER_FAILED O WhatsApp Web da instância não concluiu o pedido de figurinha (502)
INVALID_QUICK_REPLY Rotas de resposta rápida: atalho/mensagem fora das regras ou id malformado (400)
QUICK_REPLY_NOT_FOUND Não há resposta rápida com esse id na conta (404; no envio, em message.delivery_failed)
QUICK_REPLY_SHORTCUT_TAKEN Outra resposta rápida já usa esse atalho (409)
QUICK_REPLIES_NOT_SUPPORTED Respostas rápidas só no wwebjs (501) e em conta WhatsApp Business (422)
QUICK_REPLY_FAILED O WhatsApp Web da instância não concluiu o pedido de resposta rápida (502)
QUICK_REPLY_CHANGED No envio: a resposta foi editada depois do 202; nada foi enviado (message.delivery_failed)
IDEMPOTENCY_KEY_REQUIRED Header Idempotency-Key ausente em endpoint async
MEDIA_TOO_LARGE Arquivo excede limite de upload
UNSUPPORTED_MEDIA_TYPE MIME type não aceito
MEDIA_FETCH_FAILED API tentou baixar media_url no request e falhou (DNS, 4xx/5xx do origem, SSRF, timeout, oversized). HTTP 502. Sem retry — request inteiro falha sincronamente. Retry com URL válida ou faca upload prévio em /media. Também usado pelo redownload-media em falha transitória de download
MEDIA_NOT_REDOWNLOADABLE POST .../messages/{id}/redownload-media não consegue recuperar a mídia: wwebjs já fez eviction da mensagem do store vivo, ou a linha whatsmeow não tem proto armazenado. HTTP 404 — a mídia se foi (distinto de MEDIA_FETCH_FAILED, que é transitório)
MESSAGE_NOT_FOUND Mensagem não existe na tenant DB
TARGET_NOT_FOUND A mensagem nomeada pela chave nativa do WhatsApp (*_wa_message_id + *_wa_from_me + chat, ou a forma serializada) não está no histórico e a operação precisa do conteúdo guardado (forward, edit, label). HTTP 404. Também é o reason: "target_not_found" do *.delivery_failed quando o provider não acha um alvo nativo
INVALID_MESSAGE_KEY Chave nativa malformada, sem *_wa_from_me, de outro chat, ou com direção que a operação não aceita. HTTP 400, nada enfileirado
EDIT_UNSUPPORTED_TYPE O tipo da mensagem-alvo não tem texto editável — só corpo de texto e captions de image/video/document/gif/ptv podem ser editados. HTTP 400. Estável: use pra esconder/desabilitar a acao "Editar" na sua UI
EDIT_WINDOW_EXPIRED A janela de edicao do WhatsApp (~15 min após o envio) expirou — clientes destinatários ignorariam a edicao, então a API recusa sincronamente. HTTP 400
EDIT_FORWARDED_NOT_ALLOWED O alvo do edit é uma mensagem ENCAMINHADA — o WhatsApp não permite editar forwards (o app oficial nem oferece a acao). Recusado sincronamente, nada é enfileirado nem enviado à Meta. HTTP 400. Estável: esconda a acao de editar quando is_forwarded: true
EDIT_OTHER_DEVICE_NOT_ALLOWED Instância wwebjs e o alvo do edit foi enviado por OUTRO aparelho do mesmo número (celular, ou API oficial em coexistência — source: "external"). A WA Web só edita o que ela enviou. Recusado sincronamente, nada é enfileirado nem enviado à Meta. HTTP 400. Estável: esconda a acao de editar quando source for "external" numa instância wwebjs
FORWARD_SOURCE_DELETED A mensagem de origem de um POST .../messages/forward foi APAGADA PARA TODOS (pelo autor ou pelo DELETE desta API) — ela não existe mais no WhatsApp e nunca poderá ser encaminhada. Recusado sincronamente, nada é enfileirado nem enviado à Meta. HTTP 422. Estável: esconda "Encaminhar" em mensagens que receberam *.deleted
INVALID_PIX_KEY Chave PIX inválida para o tipo declarado (CPF/CNPJ/PHONE/EMAIL/EVP). HTTP 400
INTERACTIVE_DISABLED Endpoints de mensagem interativa (button/PIX/OTP/option-list) estão desativados — destinatários não renderizam via multi-device. HTTP 403. Ver API-MANUAL seção de mensagens + comparativo §15.9
SEND_FAILED Falha ao criar/enfileirar a task
BLOCKED_DUPLICATE_CONTENT Anti-spam guard bloqueou conteúdo identico já enviado em 24h. Bypass: header X-Force-Send: true
BLOCKED_NO_RECIPROCITY Anti-spam guard bloqueou envio consecutivo sem inbound do contato. Bypass: header X-Force-Send: true
BLOCKED_TEMPERATURE_LIMIT Regra de temperatura bloqueou outbound — max_consecutive excedido para o tier do contato (cold=3, warm=5, engaged=7, hot=10, very_hot=15). Bypass: header X-Force-Send: true (audit-logged)
INSTANCE_SEND_LOCKED (423) A trava por conta travou os envios iniciados por nós nesta instância. Respostas em conversa aberta passam. Sem bypass por X-Force-Send — só POST /v1/instances/{id}/send-unlock
ACCOUNT_SEND_BUDGET_EXCEEDED (409 + Retry-After) O teto de 24h de envios iniciados por nós da instância encheu
PASSIVE_MODE_ENABLED Instância em modo passivo (passive_mode_enabled=true) — so recebe mensagens; todo endpoint outbound responde 409 antes de qualquer throttle/fila. Bypass: header X-Force-Send: true (audit-logged)
Canal Social (Instagram)
ZERNIO_DISABLED Provider zernio desligado no deploy (ZERNIO_ENABLED=false)
META_INSTAGRAM_DISABLED Criar conta meta_instagram com a flag off (scaffold até App Review da Meta)
META_INSTAGRAM_UNSUPPORTED Feature fora do alcance do Graph (posts, mentions, ice breakers, automations, analytics, ads) — a Zernio cobre
SOCIAL_PROVIDER_UNSUPPORTED Provider não suporta a feature
SOCIAL_ACCOUNT_NOT_ON_PROVIDER A conta Instagram não foi encontrada no provider no connect
SOCIAL_PROFILE_HAS_ACCOUNTS DELETE de profile recusado — ainda há contas conectadas nele (desconecte antes)
OUTSIDE_SERVICE_WINDOW Janela de 24h (DM WhatsApp ou Instagram) fechada
PRIVATE_REPLY_WINDOW_EXPIRED Janela de 7 dias da resposta privada a comentário Instagram expirou
PUBLISHING_QUOTA_EXCEEDED Quota de publicação da plataforma Instagram atingida
ICEBREAKER_LIMIT Mais de 4 ice breakers na conta
ICEBREAKER_QUESTION_TOO_LONG Pergunta de ice breaker acima de 80 chars
ZERNIO_AUTH A API key da Zernio foi rejeitada (rotacionar)
ZERNIO_RATE_LIMIT Rate limit da Zernio
OpenAI Playground
PLAYGROUND_DISABLED Playground OpenAI desabilitado neste binario
PLAYGROUND_BUDGET_EXCEEDED Orcamento diário em USD esgotado
PLAYGROUND_RATE_LIMITED Rate limit por usuário do playground excedido
PLAYGROUND_UNSUPPORTED_KIND Tipo de geração não suportado
Webhook
WEBHOOK_NOT_FOUND Webhook não existe
WEBHOOK_URL_INVALID URL inválida (HTTP em prod, scheme não suportado, SSRF)
WEBHOOK_URL_BLOCKED URL em dominio bloqueado
Feedback
FEEDBACK_INVALID Conteúdo de feedback/bug/request inválido
FEEDBACK_FAILED Falha interna ao registrar o feedback
Conta (self-service)
INVALID_CURRENT_PASSWORD Senha atual errada em PATCH /v1/auth/me/password
PASSWORD_TOO_SHORT Nova senha abaixo do mínimo
OWNER_ONLY Ação restrita ao owner da empresa
EMAIL_ALREADY_TAKEN Novo email já em uso por outra conta
EMAIL_CHANGE_NOT_FOUND Pedido de troca de email não encontrado
EMAIL_CHANGE_CODE_INVALID Código de confirmação de troca de email inválido
EMAIL_CHANGE_LOCKED Troca de email travada por excesso de tentativas
ACCOUNT_DELETION_FAILED Falha ao excluir conta — geralmente billing inacessível ou DB inconsistente
ACCOUNT_ALREADY_DELETED Conta já estava soft-deleted (idempotente)
ACCOUNT_DELETED Tentativa de login em conta soft-deleted — rejeita antes de emitir JWT
Reputacao de IP
REPUTATION_NOT_AVAILABLE IP nunca foi checado, ou serviço de reputacao não configurado
REPUTATION_RATE_LIMITED Budget de 5/min por superadmin do check on-demand esgotado

Casando o erro do frontend com o log do backend#

Quando o frontend recebe um erro, ele também recebe o trace_id. Para encontrar a linha exata no log:

bash
TRACE_ID="2a62142c-f55f-4db4-8c7b-060018e3ef48"
TOKEN=$(curl -sf https://api.catcher.one/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@biazap.test","password":"<senha>"}' | jq -r .token)

curl -sf "https://api.catcher.one/<rota-superadmin-de-logs>?trace_id=$TRACE_ID&limit=20" \
  -H "Authorization: Bearer $TOKEN" | jq '.lines[]' -r

O endpoint superadmin de logs aceita os filtros: file, limit, skip, level, contains, instance_id, trace_id, error_code. Use trace_id para uma única request, error_code para encontrar todas as ocorrências de um erro especifico.

A linha de log do request completed inclui os campos trace_id, error_code, status, duration_ms, path, method, remote_addr — tudo o que você precisa para diagnosticar o problema.