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:
{
"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:
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.