Códigos de erro — API de dados do WhatsApp
Todas as respostas de erro seguem o mesmo padrão: status HTTP + mensagem de erro + código numérico + registro de data e hora.
Formas de envelope (observadas)
O proxy retorna uma de duas formas, dependendo do modo de falha:
Erro breve (autenticação / limite de burst / validação):
{ "error": "Requests must be at least 0.5 seconds apart" }Erro detalhado (falha na pesquisa em /number/no_picture/{n}, /number-simple/{n}) — o corpo ainda é analisado como um WhatsAppEntry com campos extras:
{
"number": "13105551234",
"isWAContact": true,
"error": "Whatsapp number doesn't exist",
"exists": false,
"reason": "not_found",
"status": 404,
...
}Verifique sempre o campo de erro, mesmo em respostas 200 (por exemplo, /number_cache pode retornar 200 com uma mensagem de erro dentro).
Status HTTP comuns
| HTTP | Significado | Ação |
|---|---|---|
| 400 | Número de telefone inválido — deve corresponder a ^[0-9]+$ (apenas dígitos, sem +). | Remova os caracteres não numéricos antes de enviar. Valide localmente com a biblioteca libphonenumber. |
| 401 | Cabeçalho x-rapidapi-key ausente ou inválido. | Adicione os cabeçalhos x-rapidapi-key e x-rapidapi-host: wp-data.p.rapidapi.com. |
| 403 | É necessário um plano ativo, a sua quota foi esgotada ou o dispositivo não pertence ao seu plano. | Verifique sua assinatura do RapidAPI. Atualize seu plano ou faça uma recarga. |
| 404 | Ponto de extremidade ou recurso não encontrado. | Verifique o caminho da URL. Para /number/{number}, um número desconhecido ainda retorna um WhatsAppEntry com isWAContact: false — verifique o corpo da mensagem, não o status. |
| 429 | Limite de requisições — requisições muito próximas umas das outras. Corpo: {"error":"Requests must be at least 0.5 seconds apart"}. | Aguarde pelo menos 500 ms entre as solicitações (2 requisições/seg). MEGA: 250 ms (4 requisições/seg). Consulte /api-key-stats → roleInfo.minIntervalSeconds para confirmar o intervalo do seu plano. |
| 500 | Falha inesperada no servidor. | Tente novamente com recuo exponencial. Informe se o problema persistir. |
| 502 / 503 | O diretório upstream do WhatsApp está indisponível ou a taxa de serviço está limitada pelo servidor upstream. | Tente novamente com um intervalo de espera. Verifique /api-status. |
| 504 | A pesquisa upstream expirou. | Tente novamente. Tente /number/no_picture/{number} para uma resposta mais rápida. |
Estratégia de repetição
- Tentativa de repetição: 429 (com Tentativa de Repetição Após), 500, 502, 503, 504.
- Não tente novamente: 400, 401, 403, 404.
- Recuo: exponencial com jitter. Limite de 5 tentativas. Sempre respeitar a opção "Tentar novamente após".
Exemplo 429 corpo
HTTP/1.1 429 Too Many Requests
content-type: application/json
{ "error": "Requests must be at least 0.5 seconds apart" }Relacionado
O Que Nossos Usuários Dizem
Avaliações reais de nossos clientes satisfeitos
Carregando avaliações...