首页
/
文档
/
错误代码 — WhatsApp 数据 API

错误代码 — WhatsApp 数据 API

所有错误响应都遵循相同的格式：HTTP 状态 + 错误消息 + 数字代码 + 时间戳。

信封形状（观察到的）

代理程序会根据故障模式返回以下两种形状之一：

短错误（身份验证/突发限制/验证）：

{ "error": "Requests must be at least 0.5 seconds apart" }

详细错误（在 /number/no_picture/{n}、/number-simple/{n} 上查找失败）——正文仍然解析为带有额外字段的 WhatsAppEntry：

{
  "number": "13105551234",
  "isWAContact": true,
  "error":  "Whatsapp number doesn't exist",
  "exists": false,
  "reason": "not_found",
  "status": 404,
  ...
}

即使是 200 响应，也务必检查错误字段（例如，/number_cache 可能会返回 200，但其中包含错误消息）。

常见的HTTP状态

HTTP	意义	行动
400	无效的电话号码 — 必须匹配 ^[0-9]+$（仅限数字，不包含 +）。	发送前去除非数字字符。使用本地 libphonenumber 库进行验证。
401	缺少或无效的 x-rapidapi-key 标头。	添加标头 x-rapidapi-key 和 x-rapidapi-host: wp-data.p.rapidapi.com。
403	需要激活套餐、配额已用完或终端不在您的套餐级别内。	查看 RapidAPI 订阅信息。升级套餐或充值。
404	未找到端点或资源。	请验证 URL 路径。对于 /number/{number}，即使输入的是未知号码，WhatsAppEntry 仍然会返回 isWAContact: false 的响应——请检查响应正文，而不是状态。
429	突发限制——请求过于密集。正文：{"error":"Requests must be at least 0.5 seconds apart"}。	请求之间至少间隔 500 毫秒（每秒 2 个请求）。MEGA 模式：250 毫秒（每秒 4 个请求）。请读取 /api-key-stats → roleInfo.minIntervalSeconds 以确认您的方案的请求频率。
500	服务器端发生意外故障。	使用指数退避算法重试。如果问题仍然存在，请报告。
502 / 503	上游 WhatsApp 目录不可用，或上游服务速率受到限制。	使用退避策略重试。检查 /api-status。
504	上游查询超时。	请重试一次。尝试使用 /number/no_picture/{number} 以获得更快的响应。

重试策略

重试：429（带重试后）、500、502、503、504。
不要重试：400、401、403、404。
退避策略：指数级加抖动。重试次数上限为 5 次。始终遵循重试后策略。

例 429 主体

HTTP/1.1 429 Too Many Requests
content-type: application/json

{ "error": "Requests must be at least 0.5 seconds apart" }

有关的

用户评价

来自满意客户的真实评价

正在加载评论...