# Erros

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

## 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
HTTP/1.1 401 Unauthorized
Content-Type: application/json
X-Request-Id: req_01a1c036cb127000b175ffba86a20018
```

```json
{
  "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"
  }
}
```

## Campos

| 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

- 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](/api/limits#idempotency-key).

## 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: no
- 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: no
- 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](/api/authentication).

### invalid_api_key
- Status HTTP: 401
- Pode repetir: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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](/api/authentication#tipos-de-chave).

### two_factor_required
- Status HTTP: 403
- Pode repetir: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: yes
- 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](/api/limits).

### internal_error
- Status HTTP: 500
- Pode repetir: yes
- 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: yes
- 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: no
- 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: no
- 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: no
- 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: no
- 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: yes
- 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: no
- 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: yes
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: yes
- 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: yes
- 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](/api/limits).

### template_error
- Status HTTP: 422
- Pode repetir: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: yes
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: yes
- 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: no
- 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: no
- 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: yes
- 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](/api/limits).

### account_flagged
- Status HTTP: 403
- Pode repetir: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: yes
- O que significa: Senhas erradas demais em seguida bloquearam o link por um tempo.
- O que fazer: Espere `retry_after_ms` e tente de novo com a senha certa.

### link_password_required
- Status HTTP: 401
- Pode repetir: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: yes
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: yes
- 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: no
- 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: no
- 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: no
- 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: yes
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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: no
- 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

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`](/errors#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`](/errors#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`](/errors#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](/guides/campaigns/#131049-e-as-24-horas), pausa sozinha a partir de 10 %. |
| 131048 | [`meta_spam_rate_limited`](/errors#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`](/errors#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](/api/limits#limite-por-par). |
| 130429 · 80007 · 4 | [`meta_rate_limited`](/errors#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](/api/limits#envio-por-número). |
| 132000 | [`template_error`](/errors#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`](/errors#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`](/errors#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`](/errors#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`](/errors#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`](/errors#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`](/errors#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`](/errors#template_error) | 422 | O Flow do template está bloqueado ou com limite atingido. | Corrija o Flow no Gerenciador do WhatsApp. |
| 368 · 131031 | [`policy_blocked`](/errors#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`](/errors#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`](/errors#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`](/errors#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`](/errors#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`](/errors#call_permission_required) | 403 | O contato não deu permissão para a empresa ligar. | Peça a permissão (veja [Ligações](/guides/calls/)) e espere `call.permission_updated`. |
| 138xxx (limites de ligação) | [`call_rate_limited`](/errors#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`](/errors#call_error) | 422 | A Meta recusou a ação da ligação. | Veja `details[0].message`. |
| 139001 | [`flow_invalid_json`](/errors#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`](/errors#flow_error) | 422 | A Meta recusou a operação no Flow. | Veja `details[0].message`. |
| 200 · 10 em catálogo | [`commerce_permission_missing`](/errors#commerce_permission_missing) | 403 | Falta a permissão `catalog_management` ao app. | Reconecte aceitando a permissão de catálogo. |
| 133005 | [`pin_invalid`](/errors#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`](/errors#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`](/errors#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`](/errors#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`](/errors#meta_invalid_parameter) | 400 | Parâmetro inválido na chamada. | Corrija o campo citado em `details[0].message`. |
| 131000 · 131016 · 133004 · 5xx | [`meta_unavailable`](/errors#meta_unavailable) | 503 | A Meta está fora do ar ou sobrecarregada, numa leitura. | Repita com backoff. |
| 131000 · 131016 · 133004 · 5xx | [`meta_unknown_outcome`](/errors#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`](/errors#meta_error) | 502 | Código da Meta sem tradução no Messajo. | Veja `meta_code` e `details[0].message`. |

### 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`](/errors#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`](/errors#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`](/errors#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`](/errors#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`](/errors#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`](/errors#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`](/errors#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`](/errors#meta_permission_denied) | 403 | Falta uma permissão para essa ação. | Reconecte aceitando todas as permissões. |
| 100 / 2018047 | [`media_error`](/errors#media_error) | 422 | Anexo recusado (tipo, tamanho ou URL). | Confira o formato e o tamanho; use `media_id`. |
| 368 · 10 / 2018320 | [`policy_blocked`](/errors#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`](/errors#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`](/errors#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`](/errors#meta_unavailable) | 503 | A Meta está fora do ar, numa leitura. | Repita com backoff. |
| 1 · 2 · 5xx | [`meta_unknown_outcome`](/errors#meta_unknown_outcome) | 502 | Mesma falha, num envio: a mensagem pode ter saído. | **Não** reenvie às cegas; veja abaixo. |
| outro | [`meta_error`](/errors#meta_error) | 502 | Código da Meta sem tradução no Messajo. | Veja `meta_code` e `details[0].message`. |

### 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

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.
