Códigos de error — API de datos de WhatsApp
Todas las respuestas de error siguen el mismo formato: estado HTTP + mensaje de error + código numérico + marca de tiempo.
Formas de sobre (observadas)
El proxy devuelve una de dos formas dependiendo del modo de fallo:
Error breve (autenticación / límite de ráfaga / validación):
{ "error": "Requests must be at least 0.5 seconds apart" }Error detallado (fallo de búsqueda en /number/no_picture/{n}, /number-simple/{n}) — el cuerpo aún se analiza como una WhatsAppEntry con campos adicionales:
{
"number": "13105551234",
"isWAContact": true,
"error": "Whatsapp number doesn't exist",
"exists": false,
"reason": "not_found",
"status": 404,
...
}Compruebe siempre el campo de error, incluso en las respuestas 200 (por ejemplo, /number_cache puede devolver 200 con un mensaje de error en su interior).
Estados HTTP comunes
| HTTP | Significado | Acción |
|---|---|---|
| 400 | Número de teléfono no válido: debe coincidir con ^[0-9]+$ (solo dígitos, sin +). | Elimine los caracteres que no sean dígitos antes de enviarlos. Valide localmente con libphonenumber. |
| 401 | Encabezado x-rapidapi-key faltante o no válido. | Agregue los encabezados x-rapidapi-key y x-rapidapi-host: wp-data.p.rapidapi.com. |
| 403 | Se requiere un plan activo, la cuota se ha agotado o el punto final no está en su nivel. | Comprueba tu suscripción a RapidAPI. Actualiza tu plan o recarga. |
| 404 | No se encontró el punto final o el recurso. | Verifica la ruta de la URL. Para /number/{number}, un número desconocido aún devuelve una WhatsAppEntry con isWAContact: false; revisa el cuerpo, no el estado. |
| 429 | Límite de ráfaga: solicitudes demasiado cercanas entre sí. Cuerpo: {"error":"Requests must be at least 0.5 seconds apart"}. | Espere al menos 500 ms entre solicitudes (2 solicitudes/seg). MEGA: 250 ms (4 solicitudes/seg). Consulte /api-key-stats → roleInfo.minIntervalSeconds para confirmar el ritmo de su plan. |
| 500 | Fallo inesperado del servidor. | Reintentar con retroceso exponencial. Informar si persiste. |
| 502 / 503 | El directorio de WhatsApp de origen no está disponible o el servicio está limitado por la velocidad de subida. | Reintentar con retroceso. Comprobar /api-status. |
| 504 | La búsqueda ascendente ha expirado. | Inténtalo de nuevo. Prueba con /number/no_picture/{number} para una respuesta más rápida. |
Estrategia de reintento
- Reintento: 429 (con Reintentar-Después), 500, 502, 503, 504.
- No volver a intentar: 400, 401, 403, 404.
- Retroceso: exponencial con fluctuación. Límite de 5 reintentos. Siempre se debe respetar la opción Reintentar después.
Ejemplo 429 cuerpo
HTTP/1.1 429 Too Many Requests
content-type: application/json
{ "error": "Requests must be at least 0.5 seconds apart" }Relacionado
Lo Que Dicen Nuestros Usuarios
Reseñas reales de nuestros clientes satisfechos
4.5/5 (173 reseñas)