> For the complete documentation index, see [llms.txt](https://docs.otima.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otima.io/whatsapp/codigos-de-erros.md).

# Códigos de erros

Códigos de erro da WhatsApp Cloud API, causas e ações recomendadas.

### Como interpretar uma resposta de erro

A API retorna erros no objeto `error`. Registre `code`, `message`, `error_data.details` e `fbtrace_id`.

```json
{
  "error": {
    "message": "...",
    "type": "OAuthException",
    "code": 131026,
    "error_data": { "details": "..." },
    "fbtrace_id": "..."
  }
}
```

O texto em `message` pode variar. Use sempre o valor de `code` para tratar a falha.

Cada exemplo usa a estrutura oficial de erro. A Meta pode alterar `message` e `fbtrace_id`.

{% hint style="info" %}
A Meta pode incluir novos códigos ou alterar mensagens. Consulte a [referência oficial de erros](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/) antes de liberar uma regra de tratamento.
{% endhint %}

### Erros de autenticação, permissão e limite

#### Código 0 — Exceção de autenticação

```json
{
  "error": {
    "message": "Authentication exception",
    "type": "OAuthException",
    "code": 0,
    "fbtrace_id": "..."
  }
}
```

Ocorre uma falha interna de autenticação. Confirme o token e repita a requisição uma vez. Se persistir, envie o `fbtrace_id` ao suporte.

#### Código 3 — Método da API não existe

```json
{
  "error": {
    "message": "Unsupported get request",
    "type": "OAuthException",
    "code": 3,
    "fbtrace_id": "..."
  }
}
```

A rota ou o método HTTP não é válido para o objeto solicitado. Confirme a versão da Graph API, o ID do objeto e o método `GET`, `POST` ou `DELETE`.

#### Código 4 — Limite de requisições da aplicação

```json
{
  "error": {
    "message": "Application request limit reached",
    "type": "OAuthException",
    "code": 4,
    "fbtrace_id": "..."
  }
}
```

A aplicação excedeu o limite de chamadas. Reduza a concorrência e implemente repetição com espera exponencial e aleatória.

#### Código 10 — Permissão negada

```json
{
  "error": {
    "message": "Application does not have permission",
    "type": "OAuthException",
    "code": 10,
    "fbtrace_id": "..."
  }
}
```

O token não possui a permissão exigida. Revise as permissões do aplicativo e o vínculo do usuário de sistema à empresa e à WABA.

#### Código 100 — Parâmetro inválido

```json
{
  "error": {
    "message": "Invalid parameter",
    "type": "OAuthException",
    "code": 100,
    "fbtrace_id": "..."
  }
}
```

Há um campo inválido, ausente ou incompatível. Leia `error_data.details`, valide o payload e confira o tipo de mensagem enviado.

#### Código 190 — Token de acesso inválido ou expirado

```json
{
  "error": {
    "message": "Invalid OAuth access token",
    "type": "OAuthException",
    "code": 190,
    "fbtrace_id": "..."
  }
}
```

O token é inválido, expirou ou foi revogado. Gere um token válido, confirme sua expiração e atualize o segredo armazenado.

#### Código 200 — Permissão insuficiente

```json
{
  "error": {
    "message": "Permissions error",
    "type": "OAuthException",
    "code": 200,
    "fbtrace_id": "..."
  }
}
```

O usuário de sistema ou o aplicativo não tem acesso ao recurso. Conceda acesso à WABA e ao número na configuração do Business Manager.

#### Código 368 — Ação temporariamente bloqueada

```json
{
  "error": {
    "message": "The action attempted has been deemed abusive or is otherwise disallowed",
    "type": "OAuthException",
    "code": 368,
    "fbtrace_id": "..."
  }
}
```

A Meta bloqueou a ação por atividade que violou políticas ou pareceu abusiva. Suspenda novas tentativas, revise a operação e aguarde a liberação.

#### Código 80007 — Limite de taxa do WhatsApp

```json
{
  "error": {
    "message": "Rate limit hit",
    "type": "OAuthException",
    "code": 80007,
    "fbtrace_id": "..."
  }
}
```

A operação atingiu um limite de taxa do WhatsApp. Enfileire os envios, diminua a taxa e tente novamente após alguns segundos.

### Erros gerais da WhatsApp Cloud API

#### API Error (400): unknown error — Erro desconhecido

```json
{
  "error": {
    "message": "unknown error",
    "type": "OAuthException",
    "code": 400,
    "fbtrace_id": "..."
  }
}
```

A requisição foi rejeitada com HTTP `400`, sem um código detalhado da Meta. Verifique o corpo completo da resposta, especialmente `error_data.details`, e valide o payload. Corrija qualquer campo inválido antes de reenviar. Se persistir com o mesmo payload, registre o `fbtrace_id` e acione o suporte.

#### Código 131000 — Erro genérico

```json
{
  "error": {
    "message": "Something went wrong",
    "type": "OAuthException",
    "code": 131000,
    "fbtrace_id": "..."
  }
}
```

A Meta não concluiu a operação e não retornou uma causa específica. Repita a requisição uma vez. Persistindo, registre o `fbtrace_id`.

#### Código 131005 — Acesso negado

```json
{
  "error": {
    "message": "Access denied",
    "type": "OAuthException",
    "code": 131005,
    "fbtrace_id": "..."
  }
}
```

O recurso existe, mas a conta não pode acessá-lo. Confirme a propriedade do número, a WABA associada e as permissões do token.

#### Código 131008 — Parâmetro obrigatório ausente

```json
{
  "error": {
    "message": "Required parameter is missing",
    "type": "OAuthException",
    "code": 131008,
    "fbtrace_id": "..."
  }
}
```

O payload não contém um campo obrigatório. Compare o corpo enviado com o esquema do tipo de mensagem.

#### Código 131009 — Valor de parâmetro inválido

```json
{
  "error": {
    "message": "Parameter value is not valid",
    "type": "OAuthException",
    "code": 131009,
    "fbtrace_id": "..."
  }
}
```

Um campo possui valor, formato ou combinação inválida. Verifique números no formato internacional, URLs, tamanhos e limites do recurso.

#### Código 131016 — Serviço indisponível

```json
{
  "error": {
    "message": "Service unavailable",
    "type": "OAuthException",
    "code": 131016,
    "fbtrace_id": "..."
  }
}
```

O serviço da Meta está temporariamente indisponível. Reenvie com espera exponencial. Não trate como falha definitiva.

#### Código 131021 — Destinatário não consegue receber a mensagem

```json
{
  "error": {
    "message": "Recipient cannot receive this message",
    "type": "OAuthException",
    "code": 131021,
    "fbtrace_id": "..."
  }
}
```

O destinatário não está disponível para receber a mensagem naquele momento. Não reenvie imediatamente. Aguarde nova interação ou tente mais tarde.

#### Código 131026 — Mensagem não entregue

```json
{
  "error": {
    "message": "Message undeliverable",
    "type": "OAuthException",
    "code": 131026,
    "fbtrace_id": "..."
  }
}
```

O WhatsApp não conseguiu entregar a mensagem. O número pode estar inativo, inválido ou indisponível. Valide o destinatário e não faça reenvios repetidos.

#### API Error: Message undeliverable — Mensagem não pode ser entregue

```json
{
    "error":{
        "message":"Message undeliverable",
        "type":"OAuthException",
        "code":131026,
        "fbtrace_id":"..."
    }
}
```

O WhatsApp não pode entregar a mensagem ao destinatário. Esse texto pode representar o erro `131026`, quando a resposta não expõe o código. O número pode estar inválido, inativo ou indisponível. Não reenvie automaticamente. Registre a resposta completa e tente novamente somente após nova interação ou confirmação de disponibilidade.

#### Código 131031 — Conta bloqueada

```json
{
  "error": {
    "message": "Account has been locked",
    "type": "OAuthException",
    "code": 131031,
    "fbtrace_id": "..."
  }
}
```

A conta do WhatsApp Business está bloqueada. Interrompa os envios e verifique o status e as políticas no Business Manager.

#### Código 131032 — Conta empresarial restrita

```json
{
  "error": {
    "message": "Business account is restricted",
    "type": "OAuthException",
    "code": 131032,
    "fbtrace_id": "..."
  }
}
```

A empresa ou a WABA possui restrições. Revise a qualidade, a verificação da empresa e os alertas da Meta antes de retomar os envios.

#### Código 131037 — Conta em modo de manutenção

```json
{
  "error": {
    "message": "Account is in maintenance mode",
    "type": "OAuthException",
    "code": 131037,
    "fbtrace_id": "..."
  }
}
```

A conta não aceita a operação durante manutenção. Reenvie posteriormente. Preserve a mensagem na fila até receber sucesso ou expiração.

#### Código 131038 — Limite de mensagens excedido

```json
{
  "error": {
    "message": "Message limit has been reached",
    "type": "OAuthException",
    "code": 131038,
    "fbtrace_id": "..."
  }
}
```

O número excedeu a capacidade permitida pela Meta. Controle a taxa por número e distribua o volume por números elegíveis.

#### Código 131042 — Elegibilidade da empresa insuficiente

```json
{
  "error": {
    "message": "Business is not eligible",
    "type": "OAuthException",
    "code": 131042,
    "fbtrace_id": "..."
  }
}
```

A empresa não atende a um requisito da funcionalidade. Confirme a verificação empresarial, a qualidade da conta e a elegibilidade do recurso.

#### Código 131045 — Certificado inválido

```json
{
  "error": {
    "message": "Invalid certificate",
    "type": "OAuthException",
    "code": 131045,
    "fbtrace_id": "..."
  }
}
```

O certificado associado à operação é inválido ou expirou. Gere ou substitua o certificado conforme a configuração afetada.

#### Código 131047 — Janela de atendimento expirada

```json
{
  "error": {
    "message": "Re-engagement message",
    "type": "OAuthException",
    "code": 131047,
    "fbtrace_id": "..."
  }
}
```

A mensagem livre foi enviada após a janela de atendimento de 24 horas. Envie um template aprovado ou aguarde uma nova mensagem do usuário.

#### Código 131048 — Limite de qualidade excedido

```json
{
  "error": {
    "message": "Spam rate limit hit",
    "type": "OAuthException",
    "code": 131048,
    "fbtrace_id": "..."
  }
}
```

A qualidade ou o limite de envio da conta impediu o envio. Reduza campanhas, melhore o consentimento e monitore a qualidade do número.

#### Código 131049 — Marketing não permitido

```json
{
  "error": {
    "message": "Message blocked to protect user privacy",
    "type": "OAuthException",
    "code": 131049,
    "fbtrace_id": "..."
  }
}
```

O destinatário não pode receber esta mensagem de marketing. Não reenvie. Use uma comunicação permitida somente quando houver base legal e elegibilidade.

#### Código 131051 — Tipo de mensagem não suportado

```json
{
  "error": {
    "message": "Unsupported message type",
    "type": "OAuthException",
    "code": 131051,
    "fbtrace_id": "..."
  }
}
```

O tipo enviado não é compatível com o destinatário, a versão ou a conta. Escolha um tipo suportado e valide os campos específicos.

#### Código 131052 — Falha ao baixar mídia

```json
{
  "error": {
    "message": "Media download error",
    "type": "OAuthException",
    "code": 131052,
    "fbtrace_id": "..."
  }
}
```

A Meta não conseguiu baixar a mídia da URL fornecida. Garanta URL pública em HTTPS, resposta rápida e formato compatível.

#### Código 131053 — Falha ao enviar mídia

```json
{
  "error": {
    "message": "Media upload error",
    "type": "OAuthException",
    "code": 131053,
    "fbtrace_id": "..."
  }
}
```

A mídia não pôde ser carregada ou processada. Valide o arquivo, o MIME type, o tamanho e o identificador de mídia.

#### Código 131056 — Limite de pareamento excedido

```json
{
  "error": {
    "message": "Pairing rate limit hit",
    "type": "OAuthException",
    "code": 131056,
    "fbtrace_id": "..."
  }
}
```

O número atingiu um limite relacionado ao registro ou pareamento. Aguarde antes de repetir e evite tentativas concorrentes.

#### Código 131057 — Conta em manutenção

```json
{
  "error": {
    "message": "Account is in maintenance mode",
    "type": "OAuthException",
    "code": 131057,
    "fbtrace_id": "..."
  }
}
```

A conta está indisponível durante manutenção. Mantenha a operação em fila e tente novamente após o período informado.

### Erros de templates

#### Código 132000 — Quantidade de parâmetros inválida

```json
{
  "error": {
    "message": "Number of parameters does not match the expected number",
    "type": "OAuthException",
    "code": 132000,
    "fbtrace_id": "..."
  }
}
```

O template recebeu mais ou menos parâmetros que o aprovado. Conte as variáveis em cada componente e envie exatamente a mesma quantidade.

#### Código 132001 — Template não existe

```json
{
  "error": {
    "message": "Template does not exist",
    "type": "OAuthException",
    "code": 132001,
    "fbtrace_id": "..."
  }
}
```

O nome, idioma ou WABA do template não corresponde a um template aprovado. Confirme `name`, `language.code` e o status do template.

#### Código 132005 — Template traduzido não existe

```json
{
  "error": {
    "message": "Translated template does not exist",
    "type": "OAuthException",
    "code": 132005,
    "fbtrace_id": "..."
  }
}
```

A tradução solicitada não está disponível. Use um idioma aprovado ou crie e aprove a tradução necessária.

#### Código 132007 — Formato do template inválido

```json
{
  "error": {
    "message": "Template format is invalid",
    "type": "OAuthException",
    "code": 132007,
    "fbtrace_id": "..."
  }
}
```

Os componentes enviados não correspondem à estrutura aprovada. Revise `header`, `body`, `footer` e `buttons`.

#### Código 132012 — Formato de parâmetro inválido

```json
{
  "error": {
    "message": "Template parameter format is invalid",
    "type": "OAuthException",
    "code": 132012,
    "fbtrace_id": "..."
  }
}
```

O tipo ou a posição do parâmetro não corresponde ao placeholder. Envie texto, moeda, data, imagem ou documento conforme o template aprovado.

#### Código 132015 — Template pausado

```json
{
  "error": {
    "message": "Template is paused",
    "type": "OAuthException",
    "code": 132015,
    "fbtrace_id": "..."
  }
}
```

A Meta pausou o template, normalmente por qualidade. Interrompa os envios e use outro template aprovado.

#### Código 132016 — Template desativado

```json
{
  "error": {
    "message": "Template is disabled",
    "type": "OAuthException",
    "code": 132016,
    "fbtrace_id": "..."
  }
}
```

O template foi desativado pela Meta. Não há reenvio possível. Crie um novo template em conformidade com as políticas.

### Erros de Flows

#### Código 132068 — Flow bloqueado

```json
{
  "error": {
    "message": "Flow is blocked",
    "type": "OAuthException",
    "code": 132068,
    "fbtrace_id": "..."
  }
}
```

O Flow não está disponível para publicação ou envio. Confirme o estado do Flow, a versão publicada e os requisitos de elegibilidade.

#### Código 132069 — Flow indisponível

```json
{
  "error": {
    "message": "Flow is unavailable",
    "type": "OAuthException",
    "code": 132069,
    "fbtrace_id": "..."
  }
}
```

O Flow ou sua configuração não pode ser usado pelo destinatário. Revise o ID, a versão, o endpoint e os campos do payload.

### Erros de registro e número

#### Código 133000 — Falha no registro

```json
{
  "error": {
    "message": "Registration failed",
    "type": "OAuthException",
    "code": 133000,
    "fbtrace_id": "..."
  }
}
```

O registro do número não foi concluído. Confirme o código de verificação, o PIN em duas etapas e a associação correta do número.

#### Código 133004 — Número temporariamente indisponível

```json
{
  "error": {
    "message": "Phone number is temporarily unavailable",
    "type": "OAuthException",
    "code": 133004,
    "fbtrace_id": "..."
  }
}
```

O número está indisponível para a operação. Aguarde e tente novamente. Não altere o cadastro durante a indisponibilidade.

#### Código 133005 — Falha na verificação em duas etapas

```json
{
  "error": {
    "message": "Two-step verification failed",
    "type": "OAuthException",
    "code": 133005,
    "fbtrace_id": "..."
  }
}
```

O PIN informado está incorreto ou não atende ao requisito. Confirme o PIN configurado para o número e repita o registro.

### Restrições de entrega e experimentos

#### Código 130472 — Destinatário em experimento

```json
{
  "error": {
    "message": "User is part of an experiment",
    "type": "OAuthException",
    "code": 130472,
    "fbtrace_id": "..."
  }
}
```

A Meta impede a entrega devido a um experimento do WhatsApp. Não há correção no payload. Não reenvie a mesma mensagem em sequência.

#### Código 130497 — País do destinatário restringe a mensagem

```json
{
  "error": {
    "message": "Message is restricted in the recipient's country",
    "type": "OAuthException",
    "code": 130497,
    "fbtrace_id": "..."
  }
}
```

O país do destinatário não aceita este tipo de mensagem. Verifique as restrições regionais e use um canal alternativo quando aplicável.

### Tratamento recomendado

1. **Corrija e reenvie:** `100`, `131008`, `131009`, `131051`, `132000`, `132007` e `132012`.
2. **Reenvie com espera:** `0`, `4`, `80007`, `131000`, `131016`, `131037`, `131038`, `131052`, `131053`, `131056`, `131057` e `133004`.
3. **Não reenvie automaticamente:** `10`, `190`, `200`, `368`, `131021`, `131026`, `131031`, `131032`, `131042`, `131047`, `131048`, `131049`, `132001`, `132005`, `132015`, `132016`, `132068`, `132069`, `133000`, `133005`, `130472` e `130497`.

Para qualquer erro persistente, envie ao suporte o horário da requisição, o código, o corpo mascarado da resposta e o `fbtrace_id`.

### Referência oficial

A lista oficial, incluindo alterações da Meta, está em [WhatsApp Cloud API — Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/).