Error Codes — WhatsApp Data API
All error responses follow the same envelope: HTTP status + error message + numeric code + timestamp.
Envelope shapes (observed)
The proxy returns one of two shapes depending on the failure mode:
Short error (auth / burst limit / validation):
{ "error": "Requests must be at least 0.5 seconds apart" }Verbose error (lookup miss on /number/no_picture/{n}, /number-simple/{n}) — body still parses as a WhatsAppEntry with extra fields:
{
"number": "13105551234",
"isWAContact": true,
"error": "Whatsapp number doesn't exist",
"exists": false,
"reason": "not_found",
"status": 404,
...
}Always check the error field even on 200 responses (e.g. /number_cache can return 200 with an error message inside).
Common HTTP statuses
| HTTP | Meaning | Action |
|---|---|---|
| 400 | Invalid phone number — must match ^[0-9]+$ (digits only, no +). | Strip non-digits before sending. Validate with libphonenumber locally. |
| 401 | Missing or invalid x-rapidapi-key header. | Add headers x-rapidapi-key and x-rapidapi-host: whatsapp-data1.p.rapidapi.com. |
| 403 | Active plan required, quota exhausted, or endpoint not on your tier. | Check RapidAPI subscription. Upgrade plan or top up. |
| 404 | Endpoint or resource not found. | Verify the URL path. For /number/{number}, an unknown number still returns a WhatsAppEntry with isWAContact: false — check the body, not the status. |
| 429 | Burst limit — requests too close together. Body: {"error":"Requests must be at least 0.5 seconds apart"}. | Sleep at least 500 ms between requests (2 req/sec). MEGA: 250 ms (4 req/sec). Read /api-key-stats → roleInfo.minIntervalSeconds to confirm your plan's pacing. |
| 500 | Unexpected server-side failure. | Retry with exponential backoff. Report if persistent. |
| 502 / 503 | Upstream WhatsApp directory unavailable, or service rate-limited from upstream. | Retry with backoff. Check /api-status. |
| 504 | Upstream lookup timed out. | Retry once. Try /number/no_picture/{number} for faster response. |
Retry strategy
- Retry: 429 (with Retry-After), 500, 502, 503, 504.
- Don't retry: 400, 401, 403, 404.
- Backoff: exponential with jitter. Cap at 5 retries. Always honor Retry-After.
Example 429 body
HTTP/1.1 429 Too Many Requests
content-type: application/json
{ "error": "Requests must be at least 0.5 seconds apart" }Related
What Our Users Say
Real reviews from our satisfied customers
4.5/5 (162 reviews)