> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wapizap.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Guia de solução de problemas comuns

# Troubleshooting

Guia para resolver os problemas mais comuns ao usar a Wapizap API.

***

## Problemas de Conexão

### Instância não conecta

<Steps>
  <Step title="Verifique o status da instância">
    ```bash theme={null}
    curl -X GET "https://api.wapizap.com/api/v2/instances/{id}/status" \
      -H "Authorization: Bearer SEU_TOKEN"
    ```
  </Step>

  <Step title="Se desconectada, gere novo QR code">
    ```bash theme={null}
    curl -X POST "https://api.wapizap.com/api/v2/instances/{id}/connect" \
      -H "Authorization: Bearer SEU_TOKEN"
    ```
  </Step>

  <Step title="Verifique dispositivos conectados no celular">
    No WhatsApp: **Configurações → Aparelhos conectados**

    Se houver 4 dispositivos, remova um antes de conectar.
  </Step>

  <Step title="Tente desconectar e reconectar">
    ```bash theme={null}
    # Desconectar
    curl -X POST "https://api.wapizap.com/api/v2/instances/{id}/disconnect" \
      -H "Authorization: Bearer SEU_TOKEN"

    # Aguardar 5 segundos e reconectar
    curl -X POST "https://api.wapizap.com/api/v2/instances/{id}/connect" \
      -H "Authorization: Bearer SEU_TOKEN"
    ```
  </Step>
</Steps>

***

### QR code expira antes de escanear

**Causa:** QR codes expiram em 60 segundos.

**Solução:**

1. Deixe o WhatsApp aberto na tela de escanear código ANTES de gerar o QR
2. Gere o QR code
3. Escaneie imediatamente

***

### Instância desconecta frequentemente

**Possíveis causas:**

* Muitos dispositivos conectados (máximo 4)
* Atividade suspeita detectada pelo WhatsApp
* Problemas de rede

**Soluções:**

1. Remova dispositivos não utilizados no WhatsApp
2. Reduza a frequência de mensagens
3. Verifique logs de erro para padrões

***

## Problemas com Mensagens

### Mensagem não enviada

<Tabs>
  <Tab title="Verificar número">
    Use o endpoint de verificação:

    ```bash theme={null}
    curl -X POST "https://api.wapizap.com/api/v2/contacts/check" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer SEU_TOKEN" \
      -d '{
        "instanceId": "sua-instancia",
        "numbers": ["5511999999999"]
      }'
    ```

    Se `exists: false`, o número não está no WhatsApp.
  </Tab>

  <Tab title="Verificar conexão">
    ```bash theme={null}
    curl -X GET "https://api.wapizap.com/api/v2/instances/{id}/status" \
      -H "Authorization: Bearer SEU_TOKEN"
    ```

    Status deve ser `connected`.
  </Tab>

  <Tab title="Verificar formato">
    O número deve estar no formato internacional sem símbolos:

    * ✅ Correto: `5511999999999`
    * ❌ Incorreto: `+55 11 99999-9999`
  </Tab>
</Tabs>

***

### Erro "Invalid number"

**Causa:** O número não está registrado no WhatsApp ou está em formato incorreto.

**Solução:**

1. Verifique o formato (deve ser `5511999999999`)
2. Use `/contacts/check` para validar
3. Confirme que o número tem WhatsApp ativo

***

### Mídia não enviada

**Verificações:**

1. URL da mídia é acessível publicamente?
2. Formato é suportado?
3. Tamanho está dentro do limite?

| Tipo      | Formatos       | Tamanho Máximo |
| --------- | -------------- | -------------- |
| Imagem    | JPG, PNG, WEBP | 16 MB          |
| Vídeo     | MP4, 3GP       | 64 MB          |
| Áudio     | MP3, OGG, M4A  | 16 MB          |
| Documento | PDF, DOC, etc  | 100 MB         |

**Teste a URL:**

```bash theme={null}
curl -I "https://sua-url.com/imagem.jpg"
# Deve retornar HTTP 200
```

***

## Problemas com Webhooks

### Webhook não recebe dados

<Steps>
  <Step title="Verifique se o webhook existe">
    ```bash theme={null}
    curl -X GET "https://api.wapizap.com/api/v2/webhooks?instanceId=sua-instancia" \
      -H "Authorization: Bearer SEU_TOKEN"
    ```
  </Step>

  <Step title="Verifique se a URL é acessível">
    ```bash theme={null}
    curl -X POST "https://seu-servidor.com/webhook" \
      -H "Content-Type: application/json" \
      -d '{"test": true}'
    ```

    Deve retornar HTTP 200.
  </Step>

  <Step title="Teste o webhook via API">
    ```bash theme={null}
    curl -X POST "https://api.wapizap.com/api/v2/webhooks/{id}/test" \
      -H "Authorization: Bearer SEU_TOKEN" \
      -d '{"instanceId": "sua-instancia"}'
    ```
  </Step>

  <Step title="Verifique os eventos configurados">
    Certifique-se de que os eventos desejados estão na lista do webhook.
  </Step>
</Steps>

***

### Webhook recebe duplicatas

**Causa:** Seu servidor pode estar demorando para responder, causando retry.

**Solução:**

1. Responda com HTTP 200 em menos de 5 segundos
2. Processe dados de forma assíncrona
3. Use `messageId` para deduplicação:

```javascript theme={null}
const processedMessages = new Set();

app.post('/webhook', (req, res) => {
  const messageId = req.body.data?.key?.id;

  if (processedMessages.has(messageId)) {
    return res.status(200).json({ duplicate: true });
  }

  processedMessages.add(messageId);

  // Processar de forma assíncrona
  processMessageAsync(req.body);

  res.status(200).json({ received: true });
});
```

***

### Webhook localhost não funciona

**Causa:** Webhooks precisam de URLs públicas.

**Solução:** Use um serviço de túnel:

```bash theme={null}
# ngrok
npx ngrok http 3000
# Copie a URL https://xxxx.ngrok.io

# ou Cloudflare Tunnel
cloudflared tunnel --url http://localhost:3000
```

***

## Problemas de Autenticação

### Erro 401 Unauthorized

**Verificações:**

1. O token está no formato correto?
   ```
   Authorization: Bearer sk_live_xxxxx
   ```

2. O token é válido e não expirou?

3. Está usando o ambiente correto (live vs test)?

**Teste:**

```bash theme={null}
curl -X GET "https://api.wapizap.com/api/v2/instances" \
  -H "Authorization: Bearer SEU_TOKEN"
```

***

### Erro 403 Forbidden

**Causa:** Sua API key não tem permissão para esta operação.

**Solução:**

1. Verifique as permissões da API key no dashboard
2. Gere uma nova key com as permissões necessárias

***

## Rate Limiting

### Erro 429 Too Many Requests

**Solução imediata:**

```javascript theme={null}
if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After') || 60;
  await sleep(retryAfter * 1000);
  // Retry
}
```

**Solução a longo prazo:**

1. Implemente queue de mensagens
2. Distribua envios ao longo do tempo
3. Use múltiplas instâncias para volume alto

***

## Ferramentas de Diagnóstico

### Verificar status geral

```bash theme={null}
# Status de todas as instâncias
curl -X GET "https://api.wapizap.com/api/v2/instances" \
  -H "Authorization: Bearer SEU_TOKEN"

# Status de instância específica
curl -X GET "https://api.wapizap.com/api/v2/instances/{id}/status" \
  -H "Authorization: Bearer SEU_TOKEN"
```

### Logs de webhook

No dashboard, vá em **Webhooks → Logs** para ver:

* Requisições enviadas
* Respostas recebidas
* Erros e retries

### Testar conectividade

```bash theme={null}
# Ping na API
curl -w "\nTempo: %{time_total}s\n" \
  -X GET "https://api.wapizap.com/health"
```

***

## Checklist de Diagnóstico

Antes de contatar o suporte, verifique:

* [ ] API key está correta e válida?
* [ ] Instância está conectada?
* [ ] Número está no formato internacional?
* [ ] URL do webhook é pública e acessível?
* [ ] Não excedeu rate limits?
* [ ] Mídia está dentro dos limites de tamanho?

***

## Contatar Suporte

Se o problema persistir:

<CardGroup cols={2}>
  <Card title="Email" icon="envelope" href="mailto:support@wapizap.com">
    [support@wapizap.com](mailto:support@wapizap.com)
  </Card>

  <Card title="Discord" icon="discord" href="https://discord.gg/wapizap">
    Comunidade Discord
  </Card>
</CardGroup>

**Inclua na sua mensagem:**

* ID da instância
* Endpoint usado
* Código de erro
* Request/Response de exemplo
* Timestamp do problema