Pular para o conteúdo

API e SDK

Erros

O formato único de erro da API e o significado de cada código.

Todo erro da API usa o mesmo corpo JSON, com um code estável que você pode tratar no seu código. Este é o corpo real de uma chamada a GET /v1/me sem chave:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
X-Request-Id: req_01a1c036cb127000b175ffba86a20018
{
"error": {
"code": "missing_api_key",
"message": "Missing API key: send Authorization: Bearer <key>",
"meta_code": null,
"retryable": false,
"request_id": "req_01a1c036cb127000b175ffba86a20018",
"docs_url": "https://docs.messajo.com/errors#missing_api_key"
}
}
Campo Tipo O que é
code string Código estável do Messajo. Trate o erro por ele, nunca pela mensagem.
message string Texto curto em inglês, bom para log. Pode mudar entre versões.
meta_code número ou null Código original da Meta quando o erro veio dela; null nos demais.
retryable booleano true quando repetir a mesma chamada pode dar certo.
request_id string Id da requisição, igual ao cabeçalho X-Request-Id.
docs_url string Link para a âncora do código nesta página.
retry_after_ms número Só nos erros de limite (rate_limited, connection_rate_limited, pair_rate_limited, meta_rate_limited, link_locked): quanto esperar, em milissegundos.
details lista Itens { path, message }. Em validation_failed, um por campo inválido. Num erro da Meta, details[0].message traz o detalhe que ela mandou (error_data.details). Em outside_service_window, o fim da janela (path: "window_ends_at").
  • Repita só quando retryable for true. Os demais pedem uma correção antes.
  • Se a resposta trouxer Retry-After (segundos) ou retry_after_ms, espere pelo menos esse tempo.
  • Sem Retry-After, use backoff exponencial com jitter (por exemplo 1 s, 2 s, 4 s…) e um teto de tentativas.
  • Envio de mensagem nunca é repetido às cegas: mande o cabeçalho Idempotency-Key e repita com a mesma chave, para não entregar a mensagem duas vezes. Veja Limites.

Cada código tem uma âncora própria (/errors#<code>), a mesma do docs_url.

validation_failed

Status HTTP
400
Pode repetir
Não
Mensagem no painel
Alguns campos estão inválidos. Revise e tente de novo.
O que significa
O corpo, a query ou os parâmetros da requisição não passaram na validação.
O que fazer
Leia details: cada item traz o path do campo e o motivo. Corrija e envie de novo.

missing_api_key

Status HTTP
401
Pode repetir
Não
Mensagem no painel
Envie a chave de API no cabeçalho Authorization.
O que significa
A requisição chegou sem o cabeçalho Authorization: Bearer.
O que fazer
Envie a chave no cabeçalho Authorization: Bearer <chave>. Cookie do painel não autentica a API; veja Autenticação.

invalid_api_key

Status HTTP
401
Pode repetir
Não
Mensagem no painel
Chave de API inválida.
O que significa
A chave enviada não existe ou foi revogada.
O que fazer
Confira se copiou a chave inteira, sem espaços. Se ela foi revogada, crie outra no painel.

api_key_expired

Status HTTP
401
Pode repetir
Não
Mensagem no painel
Esta chave de API expirou.
O que significa
A chave passou da data de validade definida na criação.
O que fazer
Crie uma chave nova no painel e troque na sua integração antes de apagar a antiga.

api_key_disabled

Status HTTP
401
Pode repetir
Não
Mensagem no painel
Esta chave de API está desativada.
O que significa
A chave existe, mas foi desativada no painel.
O que fazer
Peça a um admin da organização para reativar a chave ou use outra ativa.

unauthenticated

Status HTTP
401
Pode repetir
Não
Mensagem no painel
Sua sessão expirou. Entre de novo.
O que significa
A rota do painel exige uma sessão e ela não existe ou expirou.
O que fazer
Entre de novo no painel. Integrações devem usar a API /v1 com chave.

billing_required

Status HTTP
402
Pode repetir
Não
Mensagem no painel
Seu plano não permite esta ação. Revise a cobrança.
O que significa
O plano da organização não permite esta ação ou há cobrança pendente.
O que fazer
Revise o plano e a cobrança no painel. Repetir a chamada não resolve.

org_restricted

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Esta organização está restrita: não dá para criar itens novos até regularizar.
O que significa
A organização está restrita: não pode criar itens novos (destinos, campanhas, flows, templates, links de conexão).
O que fazer
O que já existe segue funcionando. Regularize a situação da organização no painel; repetir a chamada não resolve.

org_suspended

Status HTTP
402
Pode repetir
Não
Mensagem no painel
Esta organização está suspensa. O painel fica só para leitura até regularizar.
O que significa
A organização está suspensa: a API só responde a GET /v1/me e os webhooks ficam retidos.
O que fazer
Regularize a situação da organização no painel. Ao reativar, os webhooks retidos são entregues em ordem.

forbidden

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Você não tem permissão para fazer isso.
O que significa
Quem fez a chamada não tem acesso a este recurso.
O que fazer
Confira se a chave ou o usuário pertence à organização dona do recurso.

insufficient_permissions

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Sua chave ou seu papel não tem esta permissão.
O que significa
A chave ou o papel não tem a permissão que a rota exige.
O que fazer
Crie uma chave com a permissão necessária ou peça um papel com mais acesso.

connection_not_allowed

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Esta chave não tem acesso a esta conexão.
O que significa
A chave está restrita a outras conexões.
O que fazer
Use uma chave liberada para esta conexão ou inclua a conexão nas permissões da chave.

organization_key_required

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Esta operação exige uma chave da organização.
O que significa
Esta operação só aceita uma chave da organização (mj_), e a chave usada é de conexão (mjc_).
O que fazer
Use uma chave da organização e repita a chamada. Veja Autenticação.

two_factor_required

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Seu papel exige verificação em duas etapas. Ative o 2FA para continuar.
O que significa
Seu papel exige verificação em duas etapas e ela está desligada. Só aparece no painel.
O que fazer
Ative o 2FA em Perfil → Segurança e repita a ação.

two_factor_mandatory

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Donos e admins não podem desativar a verificação em duas etapas.
O que significa
Donos e admins não podem desligar a verificação em duas etapas. Só aparece no painel.
O que fazer
Mantenha o 2FA ligado ou peça para mudarem seu papel antes de desligar.

no_active_organization

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Escolha uma organização para continuar.
O que significa
A sessão do painel não tem uma organização escolhida.
O que fazer
Escolha ou crie uma organização no painel e repita a ação.

last_owner

Status HTTP
409
Pode repetir
Não
Mensagem no painel
A organização precisa de pelo menos um dono.
O que significa
A ação deixaria a organização sem nenhum dono.
O que fazer
Promova outro membro a dono antes de sair ou de mudar o seu papel.

slug_taken

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Este endereço já está em uso. Escolha outro.
O que significa
Já existe uma organização com este endereço.
O que fazer
Escolha outro endereço (slug) e envie de novo.

org_limit_reached

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Você atingiu o limite de organizações por usuário.
O que significa
Você atingiu o limite de organizações por usuário.
O que fazer
Exclua uma organização que não usa mais ou peça ao admin da instância para subir o limite.

reauth_failed

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Senha ou código de verificação incorreto.
O que significa
A senha ou o código de verificação da reconfirmação está incorreto.
O que fazer
Digite a senha de novo e, se tiver 2FA, o código atual de 6 dígitos.

account_delete_blocked

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Você é o único dono de uma organização com outros membros. Transfira a posse ou exclua a organização antes.
O que significa
Você é o único dono de uma organização com outros membros.
O que fazer
Transfira a posse ou exclua a organização e repita.

not_found

Status HTTP
404
Pode repetir
Não
Mensagem no painel
Não encontramos o que você procurou.
O que significa
O recurso não existe ou não pertence à organização da chave.
O que fazer
Confira o id e a organização. Recurso de outra organização também responde 404.

conflict

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Este registro mudou ou já existe. Atualize a página.
O que significa
O registro mudou ou já existe com estes dados.
O que fazer
Busque o estado atual do recurso e decida se envia de novo.

rate_limited

Status HTTP
429
Pode repetir
Sim
Mensagem no painel
Muitas tentativas. Aguarde um pouco e tente de novo.
O que significa
Você passou do limite da chave ou da organização.
O que fazer
Espere retry_after_ms (ou o Retry-After) e tente de novo; veja Limites.

internal_error

Status HTTP
500
Pode repetir
Sim
Mensagem no painel
Algo deu errado do nosso lado. Tente de novo.
O que significa
Algo falhou do nosso lado ao processar a requisição.
O que fazer
Repita com backoff. Se continuar, fale com o suporte mandando o request_id.

service_unavailable

Status HTTP
503
Pode repetir
Sim
Mensagem no painel
Serviço temporariamente indisponível. Tente de novo em instantes.
O que significa
O serviço ou uma dependência dele está fora do ar por um instante.
O que fazer
Repita com backoff exponencial respeitando o Retry-After, quando houver.

missing_signature

Status HTTP
401
Pode repetir
Não
Mensagem no painel
O webhook chegou sem assinatura.
O que significa
O webhook de entrada chegou sem o cabeçalho X-Hub-Signature-256.
O que fazer
Só a Meta (ou o seu simulador) deve chamar esta URL. Confira se a chamada vem do app certo, assinada com o app secret.

invalid_signature

Status HTTP
401
Pode repetir
Não
Mensagem no painel
A assinatura do webhook não confere.
O que significa
A assinatura sha256= do webhook não confere com o app secret configurado.
O que fazer
Confira se META_APP_SECRET é o do app que assina o webhook e se o corpo não foi alterado no caminho.

invalid_payload

Status HTTP
400
Pode repetir
Não
Mensagem no painel
O conteúdo do webhook é inválido.
O que significa
O corpo do webhook não é um JSON no formato que a Meta envia.
O que fazer
Envie o corpo exatamente como a Meta o gerou, com Content-Type: application/json.

payload_too_large

Status HTTP
413
Pode repetir
Não
Mensagem no painel
O conteúdo enviado é grande demais.
O que significa
O corpo da requisição passou do tamanho máximo aceito.
O que fazer
Reduza o conteúdo enviado. Arquivos grandes vão por mídia, não no corpo.

channel_not_configured

Status HTTP
503
Pode repetir
Sim
Mensagem no painel
Este canal ainda não está configurado no servidor.
O que significa
O canal não tem app secret configurado neste servidor, então o webhook não pode ser conferido.
O que fazer
A Meta reenvia o que recebeu 503.

idempotency_key_reused

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Esta Idempotency-Key já foi usada em outra requisição.
O que significa
A Idempotency-Key já foi usada nas últimas 24 h com outro método, caminho ou corpo.
O que fazer
Gere uma chave nova para cada operação diferente. Repita a mesma chave só para reenviar a mesma requisição.

idempotency_in_progress

Status HTTP
409
Pode repetir
Sim
Mensagem no painel
Uma requisição com esta Idempotency-Key ainda está em andamento.
O que significa
A primeira requisição com esta Idempotency-Key ainda está sendo processada.
O que fazer
Espere alguns segundos e repita com a mesma chave: você recebe a resposta guardada.

destination_url_not_allowed

Status HTTP
400
Pode repetir
Não
Mensagem no painel
Este endereço de destino não é permitido.
O que significa
A URL do destino aponta para um endereço bloqueado (rede privada, http sem permissão, host inválido).
O que fazer
Leia details[].message com o motivo e use uma URL https pública.

destination_limit_reached

Status HTTP
409
Pode repetir
Não
Mensagem no painel
A organização chegou ao limite de destinos. Remova um para criar outro.
O que significa
A organização já tem o número máximo de destinos.
O que fazer
Remova um destino que não usa mais antes de criar outro.

destination_paused

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Este destino está pausado. Retome-o para continuar.
O que significa
O destino está pausado (por você ou pela pausa automática após falhas seguidas).
O que fazer
Corrija o endpoint, retome o destino no painel e reenvie as entregas que falharam.

outside_service_window

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Fora da janela de 24 h de atendimento. Envie um template.
O que significa
O contato não manda mensagem há mais de 24 h (72 h se veio de anúncio), e só template pode abrir a conversa.
O que fazer
Envie um template aprovado. Quando o contato responder, a janela abre de novo e mensagens livres voltam a valer.

recipient_unavailable

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Não foi possível entregar a este destinatário.
O que significa
A Meta não conseguiu entregar: o número não tem WhatsApp, o app dele está desatualizado ou ele não aceitou os termos novos.
O que fazer
Confira o número com DDI. Não repita em seguida: o resultado será o mesmo até o destinatário resolver do lado dele.

marketing_limit_reached

Status HTTP
422
Pode repetir
Não
Mensagem no painel
A Meta limitou mensagens de marketing para este contato.
O que significa
A Meta segurou o template de marketing para manter o engajamento do contato saudável (limite por usuário).
O que fazer
Não reenvie em seguida. Espere alguns dias ou mande algo que o contato peça; reenvio imediato não passa.

pair_rate_limited

Status HTTP
429
Pode repetir
Sim
Mensagem no painel
Mensagens demais para este contato em pouco tempo. Aguarde alguns segundos.
O que significa
O limite por par (este número ↔ este contato) da Meta foi atingido.
O que fazer
Espere retry_after_ms (6 s) antes de mandar de novo para o mesmo contato. Outros contatos não são afetados.

meta_rate_limited

Status HTTP
429
Pode repetir
Sim
Mensagem no painel
A Meta limitou a vazão. Aguarde e tente de novo.
O que significa
A Meta recusou por limite de vazão do número, da conta ou do app, sem processar o pedido.
O que fazer
Espere retry_after_ms (ou o cabeçalho Retry-After) e repita. Veja Limites.

template_error

Status HTTP
422
Pode repetir
Não
Mensagem no painel
A Meta recusou o template. Veja o motivo nos detalhes.
O que significa
O template não existe nesse idioma, os parâmetros não batem, o texto passou do limite ou ele está pausado/desativado.
O que fazer
Leia details[].message e meta_code. Confira nome, idioma e parâmetros em Templates; pausado ou desativado precisa ser editado.

policy_blocked

Status HTTP
403
Pode repetir
Não
Mensagem no painel
A Meta bloqueou este número por violação de política.
O que significa
A Meta restringiu o número ou a conta por violar as políticas do WhatsApp Business. A conexão fica restricted.
O que fazer
Veja o motivo e o prazo na saúde da conexão e no Gerenciador do WhatsApp; recorra por lá se discordar.

connection_needs_reconnect

Status HTTP
409
Pode repetir
Não
Mensagem no painel
O acesso a esta conexão expirou. Reconecte o número.
O que significa
O token da Meta foi revogado ou expirou (senha trocada, app removido, permissão retirada). A conexão fica needs_reconnect.
O que fazer
Reconecte pelo painel ou pelo link do e-mail que enviamos. Nada sai por essa conexão até reconectar.

meta_payment_required

Status HTTP
402
Pode repetir
Não
Mensagem no painel
Há um problema de pagamento na conta do WhatsApp Business.
O que significa
A conta do WhatsApp Business está sem forma de pagamento válida, ou o pagamento falhou, ou o limite de crédito acabou.
O que fazer
Ajuste a forma de pagamento no Gerenciador de Negócios da Meta. A cobrança das mensagens é da Meta, não do Messajo.

recipient_not_allowed

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Este número de teste só envia para destinatários cadastrados.
O que significa
O número de teste da Meta só manda para até 5 destinatários cadastrados no app.
O que fazer
Cadastre o destinatário no painel do app da Meta ou conecte um número de verdade.

media_error

Status HTTP
422
Pode repetir
Não
Mensagem no painel
A Meta não conseguiu processar a mídia.
O que significa
A Meta não baixou ou não aceitou a mídia: tipo não suportado, arquivo grande demais ou link inacessível.
O que fazer
Leia details[].message. Confira tipo e tamanho aceitos e, se mandou link, que ele é público e responde rápido.

number_not_registered

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Este número ainda não está registrado na API do WhatsApp.
O que significa
O registro do número na Cloud API falhou ou foi desfeito, então a Meta não aceita envio por ele.
O que fazer
Abra a conexão no painel e tente registrar de novo. Se persistir, reconecte o número.

username_not_eligible

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Esta conta ainda não pode ter nome de usuário no WhatsApp.
O que significa
A Meta ainda não liberou nome de usuário para esta conta do WhatsApp Business (Meta 147002). Vale para sugestões e para definir o nome.
O que fazer
Nada a corrigir no Messajo. Tente de novo mais tarde; a liberação é da Meta e depende da conta.

meta_invalid_parameter

Status HTTP
400
Pode repetir
Não
Mensagem no painel
A Meta recusou um parâmetro da requisição.
O que significa
Algum campo do corpo enviado à Meta é inválido ou não existe para este tipo de mensagem.
O que fazer
Leia details[].message e meta_code, corrija o campo e envie de novo.

meta_unavailable

Status HTTP
503
Pode repetir
Sim
Mensagem no painel
A Meta está temporariamente indisponível. Tente de novo em instantes.
O que significa
A Meta respondeu com falha temporária numa leitura ou em outra chamada que pode ser repetida sem efeito duplicado.
O que fazer
Repita com backoff. Se durar, veja a página de status da Meta.

meta_unknown_outcome

Status HTTP
502
Pode repetir
Não
Mensagem no painel
A Meta não confirmou o envio. A mensagem pode ter saído; confira antes de reenviar.
O que significa
Timeout ou falha temporária da Meta num envio: não dá para saber se a mensagem saiu. Ela fica queued até o status chegar por webhook.
O que fazer
Não reenvie às cegas. Confirme pelo evento message.status ou com o contato; repetir com a mesma Idempotency-Key devolve o mesmo 502 sem reenviar. Para enviar de novo de propósito, use uma chave nova.

meta_error

Status HTTP
502
Pode repetir
Não
Mensagem no painel
A Meta devolveu um erro.
O que significa
A Meta devolveu um erro que o Messajo ainda não traduz para um código próprio.
O que fazer
Leia meta_code e details[].message e procure o código na documentação da Meta. Guarde o request_id se for abrir chamado.

connection_not_active

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Esta conexão não está ativa.
O que significa
Obsoleto: substituído por connection_pending, connection_disconnected, connection_restricted, connection_disabled e connection_needs_reconnect; some na próxima versão maior. Hoje só sai quando a org não tem nenhuma conta ativa para a ação.
O que fazer
Veja o status da conexão no painel e resolva o motivo (reconectar, concluir o cadastro ou esperar a restrição acabar).

connection_restricted

Status HTTP
409
Pode repetir
Não
Mensagem no painel
A conexão está restrita pela Meta.
O que significa
A Meta restringiu a conexão e o envio está bloqueado.
O que fazer
Veja o motivo na conexão, no painel, e espere a restrição acabar ou resolva-a na Meta.

connection_disabled

Status HTTP
409
Pode repetir
Não
Mensagem no painel
A conexão foi desativada pela Meta.
O que significa
A Meta desativou a conexão.
O que fazer
Confira o status na conexão, no painel, e abra um recurso na Meta se a desativação for indevida.

connection_disconnected

Status HTTP
409
Pode repetir
Não
Mensagem no painel
A conexão está desconectada. Reconecte para usar.
O que significa
A conexão está desconectada e não envia.
O que fazer
Reconecte a conexão no painel.

connection_pending

Status HTTP
409
Pode repetir
Não
Mensagem no painel
A configuração da conexão ainda não terminou.
O que significa
A configuração da conexão ainda não terminou.
O que fazer
Conclua o cadastro da conexão no painel antes de enviar.

pin_invalid

Status HTTP
422
Pode repetir
Não
Mensagem no painel
PIN da verificação em duas etapas incorreto.
O que significa
O PIN da verificação em duas etapas está incorreto.
O que fazer
Informe o PIN correto do número. Se o esqueceu, redefina-o no app do WhatsApp.

pin_attempts_exhausted

Status HTTP
429
Pode repetir
Sim
Mensagem no painel
Tentativas demais para este número. Tente de novo mais tarde.
O que significa
O número atingiu o limite de tentativas de registro.
O que fazer
Espere o tempo informado em retry_after_ms antes de tentar de novo.

secret_rotation_pending

Status HTTP
409
Pode repetir
Não
Mensagem no painel
O segredo anterior ainda vale. Espere ele expirar para girar de novo.
O que significa
O segredo anterior do destino ainda é válido.
O que fazer
Espere o segredo anterior expirar para girar de novo.

notification_type_locked

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Este aviso é obrigatório e não pode ser alterado.
O que significa
O tipo de aviso é obrigatório e não aceita mudança.
O que fazer
Escolha outro tipo de aviso; os de segurança e de conta são sempre enviados.

connection_rate_limited

Status HTTP
429
Pode repetir
Sim
Mensagem no painel
Esta conexão atingiu a velocidade máxima de envio. Aguarde um instante.
O que significa
O número já está mandando na velocidade máxima que a Meta permite para ele (20/s na coexistência, 80/s ou mais só na API).
O que fazer
Espere retry_after_ms e repita. Nada fica enfileirado: quem repete é a sua integração. Veja Limites.

account_flagged

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Esta conta do WhatsApp Business foi banida ou sinalizada pela Meta.
O que significa
A Meta baniu ou sinalizou esta conta do WhatsApp Business por violação, e ela não pode ser conectada.
O que fazer
Resolva a situação com a Meta no Gerenciador do WhatsApp. Depois de liberada, conecte de novo.

signup_code_invalid

Status HTTP
400
Pode repetir
Não
Mensagem no painel
O código do cadastro expirou ou é inválido. Abra a janela da Meta de novo.
O que significa
O code devolvido pela janela da Meta vale 30 s e só uma vez; ele expirou ou já foi usado.
O que fazer
Recomece a conexão e conclua sem pausa depois que a janela da Meta fechar.

signup_scope_mismatch

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Faltaram permissões na janela da Meta. Conecte de novo e aceite todas.
O que significa
A janela da Meta foi concluída sem as permissões de gerenciar e mandar mensagens pela conta do WhatsApp Business.
O que fazer
Conecte de novo e mantenha todas as permissões marcadas na janela da Meta.

signup_session_expired

Status HTTP
410
Pode repetir
Não
Mensagem no painel
A sessão de cadastro expirou. Comece de novo.
O que significa
A sessão de conexão vale 30 minutos e passou do prazo, ou foi cancelada.
O que fazer
Comece a conexão de novo no painel ou pelo link de conexão.

signup_incomplete

Status HTTP
422
Pode repetir
Não
Mensagem no painel
O cadastro terminou sem um número de telefone. Conclua escolhendo um número.
O que significa
A janela da Meta criou ou escolheu a conta do WhatsApp Business, mas não terminou com exatamente um número.
O que fazer
Conecte de novo e escolha (ou cadastre) o número na janela da Meta até o fim.

system_user_assignment_failed

Status HTTP
502
Pode repetir
Não
Mensagem no painel
Este servidor não conseguiu acesso à conta do WhatsApp. Peça ao administrador da instância para conferir o usuário do sistema da Meta.
O que significa
A Meta recusou atribuir o usuário de sistema da instância (META_SYSTEM_USER_TOKEN) à conta do WhatsApp Business, ou o token dele não enxerga a conta.
O que fazer
Quem administra a instância confere o token e o id do usuário de sistema (precisa ser admin do portfólio) e a conta conecta de novo. Nada foi gravado.

connection_already_exists

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Este número já está conectado.
O que significa
O número já tem uma conexão viva, nesta organização ou em outra.
O que fazer
Use a conexão existente. Para mudar de organização, desconecte lá primeiro.

waba_owned_by_other_org

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Esta conta do WhatsApp Business já está conectada a outra organização.
O que significa
A conta do WhatsApp Business (WABA) já está conectada a outra organização.
O que fazer
Desconecte a conta na outra organização primeiro, ou use a organização que já a tem.

invitation_invalid

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Este convite não vale mais. Peça um novo.
O que significa
Quem enviou o convite saiu da organização ou não pode mais conceder esse papel.
O que fazer
Peça a um administrador da organização que envie um novo convite.

reconnect_mismatch

Status HTTP
409
Pode repetir
Não
Mensagem no painel
A reconexão foi feita com outro número. Escolha o mesmo número da conexão.
O que significa
Na reconexão, a janela da Meta voltou com um número ou conta diferente do da conexão original.
O que fazer
Reconecte escolhendo o mesmo número. Para um número novo, crie uma conexão nova.

coex_not_on_business_app

Status HTTP
422
Pode repetir
Não
Mensagem no painel
O modo coexistência exige um número que já usa o app WhatsApp Business.
O que significa
No modo coexistência o número continua no app WhatsApp Business do celular; este número não está nele.
O que fazer
Instale e ative o número no app WhatsApp Business, ou conecte no modo só API.

mirror_path_blocked

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Este caminho da API da Meta é bloqueado pelo Messajo.
O que significa
A chamada pela camada espelho quebraria a conexão (ex.: desregistrar o número, trocar a inscrição do app) e é bloqueada.
O que fazer
Faça essa ação pelo painel ou pela rota própria do Messajo, que mantém a conexão consistente.

media_too_large

Status HTTP
413
Pode repetir
Não
Mensagem no painel
O arquivo é grande demais para este tipo de mídia.
O que significa
O arquivo passa do limite da Meta para o tipo (ex.: 16 MB para áudio e vídeo, 5 MB para imagem, 100 MB para documento).
O que fazer
Comprima o arquivo ou mande como documento, que aceita mais.

media_type_not_supported

Status HTTP
415
Pode repetir
Não
Mensagem no painel
Este tipo de arquivo não é aceito.
O que significa
O tipo do arquivo (MIME) não está entre os que o WhatsApp aceita para esse tipo de mensagem.
O que fazer
Converta para um formato aceito (ex.: JPEG/PNG, MP4, OGG/Opus, PDF) ou mande como documento.

voice_conversion_failed

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Não foi possível converter o áudio em mensagem de voz.
O que significa
A conversão do áudio para OGG/Opus (mensagem de voz) falhou: arquivo corrompido ou formato que o conversor não lê.
O que fazer
Mande o áudio já em OGG/Opus, ou como áudio comum sem voice.

template_not_found

Status HTTP
404
Pode repetir
Não
Mensagem no painel
Template não encontrado.
O que significa
Não há template com esse id, ou com esse nome e idioma, nesta conta do WhatsApp Business.
O que fazer
Confira nome e idioma em Templates, ou sincronize a lista com a Meta.

coex_not_supported

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Indisponível em número de coexistência: altere no app WhatsApp Business.
O que significa
Número em coexistência: a Meta não deixa a API mudar perfil, nome exibido nem username; isso se faz no app WhatsApp Business do celular.
O que fazer
Altere pelo app WhatsApp Business no celular conectado, ou use um número só API.

instagram_account_not_professional

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Nenhuma conta profissional do Instagram foi liberada no login. Selecione a conta na tela da Meta (ela precisa ser profissional) e tente de novo.
O que significa
Nenhuma conta profissional foi liberada no login do Instagram; a Meta só libera mensagens e conteúdo pela API para contas profissionais.
O que fazer
Na tela da Meta, selecione a conta e confirme que ela é profissional e gerenciada pela pessoa que fez o login; depois conecte de novo.

instagram_scope_missing

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Falta uma permissão do Instagram para este recurso. Reconecte a conta e aceite todas as permissões.
O que significa
A conexão foi feita sem o escopo que este recurso exige (comentários, publicação ou insights). details[0].message traz o escopo que falta.
O que fazer
Reconecte a conta do Instagram e deixe marcadas todas as permissões na janela da Meta.

oauth_state_invalid

Status HTTP
400
Pode repetir
Não
Mensagem no painel
A conexão não pôde ser confirmada. Comece de novo pelo botão de conectar.
O que significa
O retorno do login da Meta trouxe um state que não confere com a sessão de conexão aberta (adulterado, vencido ou de outra aba).
O que fazer
Comece a conexão de novo pelo painel ou pelo link de conexão, na mesma aba, sem reaproveitar endereços antigos.

messenger_no_pages

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Nenhuma Página do Facebook disponível para conectar. Confira se você é admin da Página e se a escolheu na janela da Meta.
O que significa
Nenhuma Página escolhida no Login do Facebook pode ser conectada: faltam as tarefas de mensagens/gerenciar ou ela já está conectada em outra organização.
O que fazer
Confira se você tem acesso total à Página (tarefas MESSAGING ou MANAGE), se marcou a Página na janela da Meta e se ela não está ligada em outra organização.

messenger_page_not_granted

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Esta Página não foi liberada no login do Facebook. Conecte de novo e marque a Página.
O que significa
A Página escolhida não está entre as que a pessoa liberou na janela do Login do Facebook.
O que fazer
Escolha uma Página da lista devolvida ou faça o login de novo marcando a Página que falta.

type_not_supported_by_channel

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Este tipo de conteúdo não existe neste canal.
O que significa
O type (ou o campo de perfil) enviado não existe no canal da conexão, como template no Instagram ou cards no WhatsApp.
O que fazer
Consulte os tipos aceitos por canal na referência da API e escolha um equivalente.

tag_not_supported_by_channel

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Este canal não aceita etiqueta de mensagem.
O que significa
O envio trouxe tag (como human_agent) numa conexão cujo canal não tem etiquetas, como o WhatsApp.
O que fazer
Tire o tag. No WhatsApp, fora da janela de 24 h, envie um template.

human_agent_window_closed

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Já passaram 7 dias da última mensagem do contato. Espere ele escrever de novo.
O que significa
A etiqueta human_agent só vale até 7 dias depois da última mensagem do contato, e esse prazo passou.
O que fazer
Não há como enviar até o contato escrever de novo. details traz quando a janela fechou.

human_agent_not_approved

Status HTTP
403
Pode repetir
Não
Mensagem no painel
O app ainda não tem aprovação da Meta para responder com atendente humano.
O que significa
A Meta recusou o envio com human_agent: o app não tem o recurso Human Agent aprovado no App Review.
O que fazer
Peça o recurso Human Agent no App Review do app da Meta. Até lá, responda dentro da janela de 24 h.

meta_permission_denied

Status HTTP
403
Pode repetir
Não
Mensagem no painel
A Meta negou a permissão para esta ação. Reconecte a conta e aceite todas as permissões.
O que significa
A Meta recusou a chamada por falta de permissão: escopo retirado, função removida na Página ou recurso ainda não aprovado no app.
O que fazer
Veja a saúde da conexão no painel. Reconecte aceitando todas as permissões; se continuar, confira o App Review do app da Meta.

private_reply_window_closed

Status HTTP
422
Pode repetir
Não
Mensagem no painel
O prazo para responder este comentário no Direct acabou.
O que significa
A resposta privada só pode ser enviada até 7 dias depois do comentário (em comentário de live, só durante a live).
O que fazer
Responda em público no comentário ou espere o contato mandar mensagem no Direct.

private_reply_already_sent

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Este comentário já recebeu uma resposta no Direct.
O que significa
A Meta permite uma única resposta privada por comentário, e ela já foi enviada.
O que fazer
Continue a conversa no Direct que a resposta privada abriu.

comment_not_found

Status HTTP
404
Pode repetir
Não
Mensagem no painel
Comentário não encontrado.
O que significa
Não há comentário com esse id nesta conexão, ou ele foi apagado.
O que fazer
Confira o id na lista de comentários do post ou nos eventos comment.*.

comment_not_owned

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Só dá para apagar comentários nos posts desta conta.
O que significa
O comentário está numa mídia de outra conta (por exemplo, uma menção), e a Meta só deixa apagar comentários nos posts da própria conta.
O que fazer
Oculte ou responda o comentário, ou peça ao dono do post para apagá-lo.

publication_not_editable

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Esta publicação já está em andamento e não pode mais ser alterada.
O que significa
Só publicações agendadas (scheduled) ou na fila (queued) podem ser editadas ou canceladas; esta já está sendo criada, publicada ou terminou.
O que fazer
Acompanhe o status da publicação. Se falhou, use tentar de novo; se já saiu, edite ou apague o post no Instagram.

publication_media_invalid

Status HTTP
422
Pode repetir
Não
Mensagem no painel
A mídia da publicação foi recusada. Confira formato, tamanho e duração.
O que significa
A Meta não conseguiu processar a mídia da publicação (contêiner em ERROR) ou ela está fora das regras: imagem JPEG até 8 MiB, vídeo MP4/MOV até 300 MiB (story até 100 MiB).
O que fazer
Leia details, que traz o status da Meta, ajuste o arquivo e crie a publicação de novo.

media_url_not_public

Status HTTP
422
Pode repetir
Não
Mensagem no painel
A Meta não consegue baixar a mídia: o endereço não é público.
O que significa
Para publicar, a Meta baixa a mídia pela URL, e o endereço enviado (ou o do armazenamento) não é acessível pela internet.
O que fazer
Use uma URL pública em HTTPS.

media_url_expired

Status HTTP
410
Pode repetir
Não
Mensagem no painel
O link desta mídia expirou e não pode mais ser baixado.
O que significa
A URL assinada do anexo venceu antes do download, e a Meta não emite outra.
O que fazer
Peça ao contato para enviar o arquivo de novo.

publishing_limit_reached

Status HTTP
429
Pode repetir
Sim
Mensagem no painel
A conta chegou ao limite de publicações das últimas 24 horas. Tente mais tarde.
O que significa
A conta do Instagram atingiu o limite de publicações pela API nas últimas 24 horas (content_publishing_limit).
O que fazer
Espere o tempo de retry_after_ms ou agende para mais tarde. Publicações na fila são adiadas sozinhas por até 24 h.

container_timeout

Status HTTP
504
Pode repetir
Não
Mensagem no painel
A Meta demorou demais para processar a mídia. Tente publicar de novo.
O que significa
O contêiner da publicação ficou em processamento na Meta por mais de 30 minutos.
O que fazer
Tente de novo a publicação. Se repetir, reduza o tamanho ou a duração do vídeo.

insights_not_available

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Não há insights disponíveis para este item.
O que significa
A Meta não fornece insights para este item: filho de carrossel, story vencido sem snapshot, post antigo ou conta abaixo do mínimo de seguidores.
O que fazer
Consulte o post pai do carrossel ou um período mais recente. Os dados da Meta podem atrasar até 48 h.

welcome_flow_in_use

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Este fluxo de boas-vindas está em uso num anúncio e não pode ser alterado.
O que significa
O fluxo de boas-vindas está ligado a um anúncio ativo, e a Meta não deixa alterar nem apagar.
O que fazer
Tire o fluxo do anúncio no Gerenciador de Anúncios ou crie um fluxo novo.

signed_request_invalid

Status HTTP
400
Pode repetir
Não
Mensagem no painel
O pedido da Meta chegou com assinatura inválida.
O que significa
O callback de desautorização ou de exclusão de dados chegou sem signed_request, com assinatura que não confere com o segredo do app ou com algoritmo diferente de HMAC-SHA256.
O que fazer
Confira se a URL do callback no app da Meta aponta para este servidor e se META_APP_SECRET é o do mesmo app.

data_deletion_not_found

Status HTTP
404
Pode repetir
Não
Mensagem no painel
Não encontramos um pedido de exclusão com este código.
O que significa
Não há pedido de exclusão de dados com esse código de confirmação, ou ele passou de 1 ano e foi apagado.
O que fazer
Confira o código que a Meta mostrou ao pedir a exclusão e copie o endereço inteiro.

invalid_cursor

Status HTTP
400
Pode repetir
Não
Mensagem no painel
O cursor de paginação é inválido. Recomece da primeira página.
O que significa
O cursor enviado não foi gerado por esta rota com estes mesmos filtros, ou foi alterado.
O que fazer
Envie o next_cursor exatamente como veio na resposta anterior, com os mesmos filtros. Para recomeçar, omita o cursor.

retention_out_of_range

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Escolha uma retenção entre 7 dias e o máximo desta instância.
O que significa
O prazo de retenção pedido fica abaixo de 7 dias ou acima do máximo definido pela instância (RETENTION_MAX_DAYS).
O que fazer
Escolha um valor dentro da faixa mostrada nas configurações de dados da organização.

campaign_channel_not_supported

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Campanhas só estão disponíveis em conexões do WhatsApp.
O que significa
A conexão escolhida é de um canal sem envio em massa. A Meta só permite campanhas com template no WhatsApp.
O que fazer
Escolha uma conexão do WhatsApp em connection_id.

campaign_template_not_approved

Status HTTP
422
Pode repetir
Não
Mensagem no painel
O template precisa estar aprovado e ser de marketing ou utilidade.
O que significa
O template não está APPROVED na Meta ou é de uma categoria que não entra em campanha (só MARKETING e UTILITY).
O que fazer
Aguarde a aprovação ou escolha outro template. Sincronize os templates da conexão se o status mudou na Meta há pouco.

campaign_template_mapping_invalid

Status HTTP
422
Pode repetir
Não
Mensagem no painel
O mapeamento das variáveis não cobre todos os parâmetros do template.
O que significa
Algum parâmetro do template (cabeçalho, corpo ou botão) ficou sem fonte no variable_mapping, ou a fonte não serve para aquele parâmetro.
O que fazer
Leia details: cada item traz o path do parâmetro e o motivo. Dê a ele uma coluna, um valor fixo ou o nome do contato.

campaign_not_editable

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Esta campanha não pode mais ser editada neste estado.
O que significa
Template, mapeamento e destinatários só mudam em draft. Nome e velocidade também mudam em scheduled, paused e auto_paused.
O que fazer
Desagende a campanha para voltar a draft, ou crie uma nova campanha.

campaign_invalid_state

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Esta ação não é possível no estado atual da campanha.
O que significa
A ação pedida (agendar, iniciar, pausar, retomar, cancelar) não vale a partir do status atual da campanha.
O que fazer
Consulte a campanha, veja o status e escolha uma ação permitida a partir dele.

campaign_no_recipients

Status HTTP
422
Pode repetir
Não
Mensagem no painel
A campanha não tem nenhum destinatário válido.
O que significa
A campanha não tem nenhum destinatário em pending: a lista está vazia ou todas as linhas ficaram invalid.
O que fazer
Importe destinatários e corrija as linhas inválidas (o relatório da importação mostra linha, coluna e motivo).

campaign_too_many_recipients

Status HTTP
422
Pode repetir
Não
Mensagem no painel
A lista passou do limite de destinatários da campanha.
O que significa
A importação passaria do máximo de 100 000 destinatários por campanha, ou a chamada inline trouxe mais de 10 000 linhas.
O que fazer
Divida a lista em mais de uma campanha, ou envie um arquivo CSV/JSON em vez da lista inline.

campaign_import_in_progress

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Ainda há uma importação de destinatários em andamento.
O que significa
Um arquivo de destinatários ainda está sendo processado, e a campanha não pode ser agendada, iniciada nem receber outra importação até ele acabar.
O que fazer
Acompanhe a importação até completed ou failed e tente de novo.

campaign_schedule_invalid

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Agende entre 1 minuto e 90 dias a partir de agora.
O que significa
O scheduled_at está no passado, a menos de 1 minuto de agora ou a mais de 90 dias.
O que fazer
Envie um horário em ISO 8601 com fuso dentro dessa faixa. Para disparar já, inicie a campanha em vez de agendar.

spend_cap_reached

Status HTTP
409
Pode repetir
Não
Mensagem no painel
O teto de gasto do mês foi atingido. As campanhas ficam bloqueadas até o próximo mês ou até você aumentar o teto.
O que significa
Atingiu o teto de gasto mensal da organização com "pausar campanhas" ligado, então campanhas não podem ser iniciadas ou retomadas.
O que fazer
Aumente o teto em Configurações > Custos, desligue "pausar campanhas" ou espere o próximo mês.

meta_spam_rate_limited

Status HTTP
429
Pode repetir
Não
Mensagem no painel
A Meta limitou o número por excesso de denúncias ou bloqueios.
O que significa
A Meta recusou o envio (código 131048) porque muitas mensagens deste número foram denunciadas ou bloqueadas. Campanhas pausam sozinhas com este erro.
O que fazer
Não reenvie. Revise a lista (só quem pediu para receber), o conteúdo do template e a frequência; espere a qualidade do número voltar antes de retomar.

destination_type_disabled

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Este tipo de destino está desligado neste servidor.
O que significa
O servidor não liga este tipo de destino (RabbitMQ, SQS, Kafka ou WebSocket). Destinos já criados desse tipo ficam pausados.
O que fazer
Use um webhook, ou peça a quem opera a instância para ligar DESTINATIONS_<TIPO>_ENABLED.

no_client_connected

Status HTTP
503
Pode repetir
Sim
Mensagem no painel
Nenhum cliente WebSocket está conectado a este destino.
O que significa
A entrega para o destino WebSocket não achou nenhum cliente conectado (ou nenhum confirmou o recebimento). Aparece só no último erro da entrega.
O que fazer
Mantenha um cliente conectado em /v1/ws com ticket válido; a entrega é tentada de novo e, depois das tentativas, vai para a lista de falhas.

ws_ticket_invalid

Status HTTP
401
Pode repetir
Não
Mensagem no painel
O ticket do WebSocket é inválido, venceu ou já foi usado.
O que significa
O ticket enviado ao abrir /v1/ws não existe, já venceu ou já foi usado: cada ticket vale para uma conexão só.
O que fazer
Peça um ticket novo pela API logo antes de conectar e use-o uma única vez.

ws_session_limit

Status HTTP
429
Pode repetir
Não
Mensagem no painel
Há sessões WebSocket demais abertas para este destino.
O que significa
O destino já tem o máximo de sessões WebSocket simultâneas.
O que fazer
Feche as conexões que não usa mais (ou reaproveite uma) antes de abrir outra.

data_request_in_progress

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Já existe um pedido deste tipo em andamento.
O que significa
A organização já tem um pedido de exportação ou de exclusão deste tipo na fila ou rodando.
O que fazer
Acompanhe o pedido nas configurações de dados da organização e espere ele terminar.

data_request_limit

Status HTTP
429
Pode repetir
Sim
Mensagem no painel
Limite de exportações das últimas 24 horas atingido.
O que significa
A organização já pediu 3 exportações nas últimas 24 horas.
O que fazer
Baixe uma das exportações já prontas ou tente de novo depois do tempo indicado em retry_after_ms.

data_export_expired

Status HTTP
410
Pode repetir
Não
Mensagem no painel
Esta exportação venceu e o arquivo foi apagado.
O que significa
O arquivo da exportação fica disponível por 7 dias; depois disso ele é apagado.
O que fazer
Peça uma nova exportação nas configurações de dados da organização.

calling_not_supported_in_coex

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Ligações não estão disponíveis para números em coexistência com o app WhatsApp Business.
O que significa
O número está em coexistência com o app WhatsApp Business, e a Meta não oferece a Calling API nesse modo.
O que fazer
Use um número conectado só pela API (sem o app) para receber e fazer ligações.

calling_not_enabled

Status HTTP
409
Pode repetir
Não
Mensagem no painel
As ligações não estão ativadas neste número.
O que significa
As ligações estão desligadas nas configurações do número.
O que fazer
Ative as ligações em PUT /v1/connections/{id}/calling-settings (status: ENABLED) ou nas configurações de ligação da conexão no painel.

call_not_found

Status HTTP
404
Pode repetir
Não
Mensagem no painel
Ligação não encontrada.
O que significa
A ligação não existe nesta organização.
O que fazer
Confira o id (cal_…) e se a chave tem acesso à conexão da ligação.

call_invalid_state

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Esta ação não é permitida no estado atual da ligação.
O que significa
A ação não vale no estado atual da ligação (ex.: aceitar uma ligação já encerrada).
O que fazer
Leia o status atual em details ou em GET /v1/calls/{id} e mande só as ações que esse estado permite.

call_sdp_invalid

Status HTTP
400
Pode repetir
Não
Mensagem no painel
SDP inválido.
O que significa
O SDP veio vazio, passou de 64 KiB ou não começa com v=0.
O que fazer
Mande o SDP gerado pela sua pilha WebRTC sem alterações.

call_sdp_mismatch

Status HTTP
409
Pode repetir
Não
Mensagem no painel
O SDP precisa ser o mesmo enviado no pre_accept.
O que significa
Depois do pre_accept, a Meta exige que o accept use exatamente o mesmo SDP.
O que fazer
Guarde o SDP do pre_accept e reenvie o mesmo texto no accept.

call_permission_required

Status HTTP
403
Pode repetir
Não
Mensagem no painel
O contato ainda não deu permissão para receber ligações.
O que significa
O contato não deu permissão para a empresa ligar (Meta 138006).
O que fazer
Peça a permissão com uma mensagem interactive.call_permission_request (ou template com esse botão) e espere o evento call.permission_updated.

call_rate_limited

Status HTTP
429
Pode repetir
Não
Mensagem no painel
Limite de ligações da Meta atingido.
O que significa
A Meta limitou as ligações deste número ou para este contato.
O que fazer
Espere antes de ligar de novo; não repita em laço.

call_error

Status HTTP
422
Pode repetir
Não
Mensagem no painel
A Meta recusou o pedido de ligação.
O que significa
A Meta recusou o pedido da Calling API com um código da faixa 138xxx.
O que fazer
Leia meta_code e details[0].message para o motivo; corrija o pedido antes de tentar de novo.

group_not_supported

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Grupos não estão disponíveis para este número.
O que significa
Este número não tem acesso à Groups API (ex.: número em coexistência).
O que fazer
Use um número conectado só pela API e elegível a grupos.

group_not_found

Status HTTP
404
Pode repetir
Não
Mensagem no painel
Grupo não encontrado.
O que significa
O grupo não existe nesta organização.
O que fazer
Confira o id (grp_…) e se a chave tem acesso à conexão do grupo.

group_not_active

Status HTTP
409
Pode repetir
Não
Mensagem no painel
O grupo não está ativo.
O que significa
O grupo ainda está sendo criado, foi suspenso ou apagado.
O que fazer
Espere o evento group.created antes de mandar mensagens; grupo suspenso ou apagado não recebe envio.

group_participant_limit

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Participantes demais para um grupo.
O que significa
O grupo passaria do limite de participantes (8).
O que fazer
Remova participantes antes de convidar outros.

group_message_type_not_supported

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Este tipo de mensagem não pode ser enviado para um grupo.
O que significa
A Meta só aceita texto, mídia e templates de texto ou mídia em grupos.
O que fazer
Mande um desses tipos; botões, listas e Flows não vão para grupo.

flow_not_found

Status HTTP
404
Pode repetir
Não
Mensagem no painel
Flow não encontrado.
O que significa
O Flow não existe nesta organização.
O que fazer
Confira o id (flw_…) ou o id da Meta do Flow.

flow_not_editable

Status HTTP
409
Pode repetir
Não
Mensagem no painel
O Flow só pode ser editado enquanto está em rascunho.
O que significa
O JSON só muda enquanto o Flow está em DRAFT.
O que fazer
Clone o Flow publicado (POST /v1/flows/{id}/clone) e edite a cópia.

flow_invalid_json

Status HTTP
422
Pode repetir
Não
Mensagem no painel
O JSON do Flow é inválido.
O que significa
O JSON do Flow não passou na validação (local ou da Meta, código 139001).
O que fazer
Cada item de details traz path = flow_json:<linha>:<coluna> e o motivo; corrija e envie de novo.

flow_handler_required

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Este Flow precisa de um servidor de troca de dados.
O que significa
O Flow usa o endpoint do Messajo, mas falta o servidor do cliente (handler) ou a base pública HTTPS do endpoint.
O que fazer
Configure endpoint.url (HTTPS público) no Flow; quem opera a instância precisa de FLOWS_ENDPOINT_BASE_URL com https:.

flow_key_not_uploaded

Status HTTP
409
Pode repetir
Não
Mensagem no painel
A chave de criptografia do Flow ainda não foi enviada a um número ativo.
O que significa
A chave pública dos Flows ainda não foi enviada a nenhum número ativo da conta; a Meta não consegue chamar o endpoint.
O que fazer
Espere a sincronização da chave ou gire a chave em POST /v1/connections/{id}/flow-key/rotate e tente publicar de novo.

flow_error

Status HTTP
422
Pode repetir
Não
Mensagem no painel
A Meta recusou o pedido do Flow.
O que significa
A Meta recusou o pedido de Flows com um código da faixa 139xxx.
O que fazer
Leia meta_code e details[0].message e corrija antes de tentar de novo.

catalog_not_found

Status HTTP
404
Pode repetir
Não
Mensagem no painel
Catálogo não encontrado.
O que significa
O catálogo não existe nesta organização.
O que fazer
Confira o id (cat_…) e sincronize os catálogos da conta.

catalog_not_linked

Status HTTP
409
Pode repetir
Não
Mensagem no painel
O catálogo não está ligado a esta conta do WhatsApp Business.
O que significa
O catálogo citado não está ligado à conta do WhatsApp Business da conexão.
O que fazer
Ligue o catálogo (POST /v1/catalogs/{id}/link) antes de usá-lo em mensagens.

product_not_found

Status HTTP
404
Pode repetir
Não
Mensagem no painel
Produto não encontrado.
O que significa
O produto não existe neste catálogo.
O que fazer
Confira o id (prd_…) ou o retailer_id e sincronize o catálogo.

commerce_permission_missing

Status HTTP
403
Pode repetir
Não
Mensagem no painel
Falta a permissão catalog_management para este catálogo.
O que significa
O token da conexão não tem a permissão catalog_management para este catálogo.
O que fazer
Reconecte o número concedendo acesso ao catálogo, ou use um catálogo da mesma empresa.

order_not_found

Status HTTP
404
Pode repetir
Não
Mensagem no painel
Pedido não encontrado.
O que significa
O pedido não existe nesta organização.
O que fazer
Confira o id (ord_…).

order_invalid_transition

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Esta mudança de status não é permitida no estado atual do pedido.
O que significa
O novo status não segue a ordem do pedido (ex.: shipped antes do pagamento).
O que fazer
Leia o status atual do pedido e avance um passo de cada vez.

order_reference_taken

Status HTTP
409
Pode repetir
Não
Mensagem no painel
Este reference_id já foi usado nesta conexão.
O que significa
Já existe um pedido com este reference_id nesta conexão.
O que fazer
Use um reference_id novo para cada pedido (até 35 caracteres).

order_totals_mismatch

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Os totais do pedido não fecham.
O que significa
O total não é subtotal + imposto + frete − desconto, ou o subtotal não é a soma dos itens.
O que fazer
Recalcule os valores em centavos (inteiros) e envie de novo.

payment_not_available

Status HTTP
422
Pode repetir
Não
Mensagem no painel
Forma de pagamento indisponível para este pedido.
O que significa
A forma de pagamento não está disponível para este pedido (moeda, país ou configuração da Meta).
O que fazer
Use BRL com Pix, link de pagamento ou boleto; veja o guia de comércio.

otp_template_invalid

Status HTTP
422
Pode repetir
Não
Mensagem no painel
O template de autenticação não existe ou não está aprovado.
O que significa
O template de autenticação citado não existe ou não está APPROVED.
O que fazer
Crie o template em POST /v1/templates/authentication e espere a aprovação antes de mandar códigos.

body_too_large

Status HTTP
413
Pode repetir
Não
Mensagem no painel
O corpo da requisição é grande demais para esta rota.
O que significa
O corpo da requisição passou do limite desta rota.
O que fazer
Envie um corpo menor; mídia grande vai por link ou upload próprio.

Quando a Meta recusa uma chamada da camada simples, o Messajo devolve o código dele em code, o código original da Meta em meta_code e o detalhe da Meta em details[0].message. Na camada espelho (/v1/whatsapp/...) a resposta da Meta volta como veio, sem tradução: o espelho é a própria Meta.

meta_code code HTTP O que significa O que fazer
131047 outside_service_window 422 Passaram mais de 24 horas desde a última mensagem do contato. O Messajo confere antes de chamar a Meta e responde o mesmo código. Mande um template aprovado para reabrir a conversa.
131026 recipient_unavailable 422 A mensagem não pôde ser entregue (número sem WhatsApp, versão antiga, termos não aceitos). Não repita; confirme o número com o contato por outro canal.
131049 marketing_limit_reached 422 A Meta segurou o template de marketing para preservar a experiência do usuário. Não repita logo em seguida; tente outro dia ou outro conteúdo. Numa campanha, pausa sozinha a partir de 10 %.
131048 meta_spam_rate_limited 429 A Meta limitou o número por suspeita de spam (muitas denúncias ou bloqueios). Não repita; espere algumas horas e reduza o volume. Uma campanha pausa sozinha.
131056 pair_rate_limited 429 Muitas mensagens do mesmo número para o mesmo contato em pouco tempo. Espere o retry_after_ms (6 s) e espace os envios; veja Limite por par.
130429 · 80007 · 4 meta_rate_limited 429 O número ou o app passou da vazão da Meta. Repita depois do Retry-After; veja Envio por número.
132000 template_error 422 O número de variáveis enviado não bate com o template. Envie exatamente os parâmetros que o template define.
132001 template_error 422 O template não existe no idioma pedido ou ainda não foi aprovado. Confira nome, idioma e status do template.
132005 template_error 422 O texto do template com as variáveis passou do tamanho máximo. Encurte os valores das variáveis.
132007 template_error 422 O conteúdo das variáveis viola a política da Meta. Revise o texto enviado nas variáveis.
132012 template_error 422 O formato de um parâmetro não bate com o template (ex.: imagem no lugar de texto). Envie cada parâmetro no tipo que o template define.
132015 template_error 422 O template foi pausado por baixa qualidade. O Messajo marca o template como PAUSED. Edite o template ou use outro até a qualidade voltar.
132016 template_error 422 O template foi desativado por baixa qualidade repetida. O Messajo marca o template como DISABLED. Crie um template novo.
132068 · 132069 template_error 422 O Flow do template está bloqueado ou com limite atingido. Corrija o Flow no Gerenciador do WhatsApp.
368 · 131031 policy_blocked 403 A conta foi bloqueada por violar a política da Meta. A conexão passa para Restrita. Veja o motivo no Gerenciador do WhatsApp e corrija antes de enviar de novo.
190 · 102 connection_needs_reconnect 409 O token de acesso da conexão é inválido ou expirou. A conexão passa para needs_reconnect e donos e admins recebem um e-mail com link de reconexão. Reconecte.
131042 meta_payment_required 402 Problema na forma de pagamento da conta na Meta. Corrija o pagamento no Gerenciador de Negócios.
131030 recipient_not_allowed 422 Número de teste: o destinatário não está na lista de permitidos. Adicione o destinatário no painel do app da Meta.
131051 · 131052 · 131053 media_error 422 Tipo de mensagem não suportado, ou a Meta não conseguiu baixar ou subir a mídia. Confira o formato e o tamanho; use media_id em vez de link.
138006 call_permission_required 403 O contato não deu permissão para a empresa ligar. Peça a permissão (veja Ligações) e espere call.permission_updated.
138xxx (limites de ligação) call_rate_limited 429 Passou do limite de ligações ou de pedidos de permissão da Meta. Espere; não repita em seguida.
138xxx (outros) call_error 422 A Meta recusou a ação da ligação. Veja details[0].message.
139001 flow_invalid_json 422 A Meta recusou o JSON do Flow. Corrija o ponto citado em details (flow_json:<linha>:<coluna>).
139xxx (outros) flow_error 422 A Meta recusou a operação no Flow. Veja details[0].message.
200 · 10 em catálogo commerce_permission_missing 403 Falta a permissão catalog_management ao app. Reconecte aceitando a permissão de catálogo.
133005 pin_invalid 422 O número já tem PIN de verificação em duas etapas e o PIN informado não confere. A conexão fica pending com motivo pin_required. Informe o PIN de 6 dígitos na página da conexão (ou no link de conexão). Se não lembra, redefina o PIN no Gerenciador do WhatsApp.
133016 · 133008 · 133009 pin_attempts_exhausted 429 Limite de 10 registros por número em 72 h, ou a Meta pediu espera. O Messajo conta as chamadas e não envia a 11ª. Espere o retry_after_ms da resposta.
133010 number_not_registered 409 O número não está registrado na Cloud API. Na página da conexão, use Tentar registrar de novo.
147002 username_not_eligible 422 O número ainda não pode ter nome de usuário na Meta. Tente de novo mais tarde; a liberação é da Meta.
100 meta_invalid_parameter 400 Parâmetro inválido na chamada. Corrija o campo citado em details[0].message.
131000 · 131016 · 133004 · 5xx meta_unavailable 503 A Meta está fora do ar ou sobrecarregada, numa leitura. Repita com backoff.
131000 · 131016 · 133004 · 5xx meta_unknown_outcome 502 Mesma falha, mas num envio: a mensagem pode ter saído. Não reenvie às cegas; veja abaixo.
outro meta_error 502 Código da Meta sem tradução no Messajo. Veja meta_code e details[0].message.

Instagram e Messenger usam a mesma tabela, com o código e o subcódigo da Meta (meta_code / subcódigo). O espelho (/v1/instagram/..., /v1/messenger/...) devolve a resposta da Meta sem tradução.

meta_code code HTTP O que significa O que fazer
10 / 2018278 · 10 / 2534022 outside_service_window 422 Fora da janela de 24 h (ou de 7 dias com a tag). Espere o contato escrever; resposta de pessoa pode usar tag: "human_agent".
551 · 100 / 2018001 · 100 / 2534014 recipient_unavailable 422 O contato não está disponível (bloqueou a conta, apagou o perfil ou nunca conversou). Não repita.
10 / 2018065 · 200 com tag: human_agent human_agent_not_approved 403 A tag HUMAN_AGENT foi usada sem o recurso Human Agent aprovado. Peça o recurso no App Review ou responda dentro de 24 h.
10 / 2534023 private_reply_already_sent 409 O comentário já recebeu uma resposta privada. Continue a conversa pelo Direct.
4 · 17 · 32 · 613 · 80006 meta_rate_limited 429 A conta ou o app passou da vazão da Meta. Repita depois do Retry-After.
190 · 102 connection_needs_reconnect 409 O token da conta ou da Página é inválido. A conexão passa para needs_reconnect; reconecte.
10 · 200 sem subcódigo mapeado (Messenger) connection_needs_reconnect 409 A pessoa que conectou perdeu o papel na Página. A conexão passa para needs_reconnect com motivo page_role_lost. Reconecte com alguém que administre a Página.
200 / 2018028 · 10 · 3 meta_permission_denied 403 Falta uma permissão para essa ação. Reconecte aceitando todas as permissões.
100 / 2018047 media_error 422 Anexo recusado (tipo, tamanho ou URL). Confira o formato e o tamanho; use media_id.
368 · 10 / 2018320 policy_blocked 403 A Meta bloqueou por política. A conexão passa para Restrita. Veja o motivo na Meta antes de enviar de novo.
9 / 2207042 publishing_limit_reached 429 Cota de 100 publicações em 24 h cheia. O Messajo tenta de novo a cada hora por até 24 h.
2207xxx publication_media_invalid 422 A Meta não aceitou ou não conseguiu baixar a mídia da publicação. Confira formato, tamanho e se a URL é pública.
1 · 2 · 5xx meta_unavailable 503 A Meta está fora do ar, numa leitura. Repita com backoff.
1 · 2 · 5xx meta_unknown_outcome 502 Mesma falha, num envio: a mensagem pode ter saído. Não reenvie às cegas; veja abaixo.
outro meta_error 502 Código da Meta sem tradução no Messajo. Veja meta_code e details[0].message.

Quando a Meta falha no meio de um envio (timeout, 5xx), não dá para saber se a mensagem saiu. O Messajo não tenta de novo: grava a mensagem com o erro meta_unknown_outcome e responde 502 com retryable: false. Confira com o contato ou no celular antes de mandar de novo. Repetir com a mesma Idempotency-Key devolve a mesma resposta, sem reenviar; para mandar de novo de propósito, use uma chave nova.

Mande o request_id do erro (ou o cabeçalho X-Request-Id), a hora aproximada e o code. Com o request_id o suporte encontra a requisição exata nos logs.