API e SDK
Erros
O formato único de erro da API e o significado de cada código.
Formato do erro
Seção intitulada “Formato do erro”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 UnauthorizedContent-Type: application/jsonX-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"). |
Quando repetir
Seção intitulada “Quando repetir”- Repita só quando
retryablefortrue. Os demais pedem uma correção antes. - Se a resposta trouxer
Retry-After(segundos) ouretry_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-Keye repita com a mesma chave, para não entregar a mensagem duas vezes. Veja Limites.
Códigos do Messajo
Seção intitulada “Códigos do Messajo”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 opathdo 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
/v1com 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 oRetry-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.
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-Keyjá 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-Keyainda 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,
httpsem permissão, host inválido). - O que fazer
- Leia
details[].messagecom o motivo e use uma URLhttpspú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.
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çalhoRetry-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[].messageemeta_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[].messageemeta_code, corrija o campo e envie de novo.
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
queuedaté o status chegar por webhook. - O que fazer
- Não reenvie às cegas. Confirme pelo evento
message.statusou com o contato; repetir com a mesmaIdempotency-Keydevolve 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_codeedetails[].messagee procure o código na documentação da Meta. Guarde orequest_idse 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_disabledeconnection_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_msantes 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_mse 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
codedevolvido 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.
link_invalid
- Status HTTP
- 404
- Pode repetir
- Não
- Mensagem no painel
- Este link de conexão não existe.
- O que significa
- O endereço do link está incompleto, foi digitado errado ou o link foi revogado.
- O que fazer
- Peça um link novo para quem o enviou.
link_expired
- Status HTTP
- 410
- Pode repetir
- Não
- Mensagem no painel
- Este link de conexão expirou.
- O que significa
- O link passou da data de validade (no máximo 30 dias).
- O que fazer
- Peça um link novo para quem o enviou.
link_used
- Status HTTP
- 410
- Pode repetir
- Não
- Mensagem no painel
- Este link de conexão já foi usado.
- O que significa
- O link é de uso único e já conectou um número.
- O que fazer
- Se precisa conectar outro número, peça um link novo.
link_locked
- Status HTTP
- 423
- Pode repetir
- Sim
- Mensagem no painel
- Muitas tentativas de senha. Este link ficou bloqueado por alguns minutos.
- O que significa
- Senhas erradas demais em seguida bloquearam o link por um tempo.
- O que fazer
- Espere
retry_after_mse tente de novo com a senha certa.
link_password_required
- Status HTTP
- 401
- Pode repetir
- Não
- Mensagem no painel
- Este link pede senha.
- O que significa
- Quem criou o link definiu uma senha para abri-lo.
- O que fazer
- Digite a senha que veio junto com o link. Sem ela, peça para quem enviou.
link_password_invalid
- Status HTTP
- 401
- Pode repetir
- Não
- Mensagem no painel
- Senha incorreta.
- O que significa
- A senha digitada não confere com a do link.
- O que fazer
- Confira a senha e tente de novo. Várias tentativas erradas bloqueiam o link por alguns minutos.
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].messagetraz 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
stateque 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
MESSAGINGouMANAGE), 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, comotemplateno Instagram oucardsno 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(comohuman_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_agentsó 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.
detailstraz 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
statusda 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 ostatusda 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_msou 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 deHMAC-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
cursorenviado não foi gerado por esta rota com estes mesmos filtros, ou foi alterado. - O que fazer
- Envie o
next_cursorexatamente como veio na resposta anterior, com os mesmos filtros. Para recomeçar, omita ocursor.
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á
APPROVEDna Meta ou é de uma categoria que não entra em campanha (sóMARKETINGeUTILITY). - 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 opathdo 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 emscheduled,pausedeauto_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
statusatual da campanha. - O que fazer
- Consulte a campanha, veja o
statuse 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 ficaraminvalid. - 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é
completedoufailede 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_atestá 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/wscom 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/wsnã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
detailsou emGET /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 oacceptuse exatamente o mesmo SDP. - O que fazer
- Guarde o SDP do
pre_accepte reenvie o mesmo texto noaccept.
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 eventocall.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_codeedetails[0].messagepara 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.createdantes 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
detailstrazpath = 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 deFLOWS_ENDPOINT_BASE_URLcomhttps:.
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/rotatee 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_codeedetails[0].messagee 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 oretailer_ide 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_managementpara 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.:
shippedantes 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_idnesta conexão. - O que fazer
- Use um
reference_idnovo 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/authenticatione 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.
Erros da Meta em meta_code
Seção intitulada “Erros da Meta em meta_code”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
Seção intitulada “Instagram e Messenger”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. |
Envio sem resposta certa
Seção intitulada “Envio sem resposta certa”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.
Falar com o suporte
Seção intitulada “Falar com o suporte”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.