SMSPVA / DOCUMENTATION
错误与限制
处理 API 错误、等待响应及结果不明的请求。
SMSPVA API
以各接口响应表为准。同一个 HTTP 状态在不同接口可能含义不同，不要用通常的 HTTP 含义替换本 API 定义。报告失败时保留 statusCode、error.type 和 error.description。
等待不是最终失败
Receive SMS 的 202 / SMS_NOT_YET_RECEIVED 使用 error 对象表示等待，这是有意设计。先识别此响应，再在订单期限内继续轮询，不要将所有 error 对象都视为最终失败。
限流与网络故障
处理各接口文档定义的限流错误，包括存在时的 ACCESS_LIMITED。各接口的限流响应请以对应说明为准。超时、连接失败或非 JSON 响应不同于已确认的 API 错误。示例不自动重试；号码申请结果未知时应先检查当前订单。
响应索引
横线表示原文档未提供结构化错误类型示例。保留不同接口的错误类型和说明差异。
| HTTP | error.type | 说明 | 方法 |
|---|---|---|---|
| 400 | APIKEY_NOT_SET | 缺少 apikey 请求头、值为空或长度不正确。 | 查询余额, 用户信息 |
| 400 | APIKEY_NOT_SET | 未收到 API 密钥。 | 运营商, 接收质量指标, 国家及运营商价格 |
| 400 | APIKEY_NOT_SET | 缺少 apikey 请求头、值为空或不足 30 个字符。 | 消息类型设置 |
| 401 | USER_NOT_FOUND | 未找到此 API 密钥对应的账户。 | 消息类型设置 |
| 402 | RATELIMIT_EXCEED | 请求频率超限；此 API 使用 HTTP 402 表示该错误。 | 消息类型设置 |
| 403 | USER_BANNED | 账户已被封禁。 | 消息类型设置 |
| 500 | SERVER_ERROR | 服务器内部错误；启用错误详情时，说明可能包含具体异常。 | 消息类型设置 |
| 402 | RATELIMIT_EXCEED | 已超过 API 请求频率限制。 | 所有号码余量 |
| 405 | INVALID_PARAMS | country 或 service 参数不正确。 | 服务价格 |
| 405 | INVALID_PARAMS | 参数不正确 | 按国家查询服务价格, 获取号码, 按运营商获取号码, 接收短信, 清除短信, 停止接收短信, 取消订单 |
| 407 | LOW_BALANCE | 余额不足以接收所选国家和服务的短信。 | 获取号码 |
| 411 | ACCESS_LIMITED | karma 过低或请求过于频繁，API 访问受限。 | 获取号码, 接收短信, 停止接收短信, 取消订单, 屏蔽号码 |
| 500 | NUMBER_FETCH_FAIL | 未能获取号码。 | 获取号码 |
| 501 | PRICE_FETCH_FAIL | 未找到号码。 | 获取号码 |
| 502 | NUMBER_NOT_FOUND | 未找到号码。 | 获取号码 |
| 503 | SERVER_BUSY | 服务器繁忙，请稍后再试。 | 获取号码 |
| 407 | — | 余额不足以接收所选国家和服务的短信。 | 按运营商获取号码 |
| 411 | — | karma 过低或请求过于频繁，API 访问受限。 | 按运营商获取号码 |
| 500 | — | 未能获取号码。 | 按运营商获取号码 |
| 501 | — | 未找到号码。 | 按运营商获取号码 |
| 502 | — | 未找到号码。 | 按运营商获取号码, 号码状态 |
| 503 | — | 服务器繁忙，请稍后再试。 | 按运营商获取号码 |
| 406 | INVALID_ORDER_FORMAT | 订单 ID 格式不正确或未找到。 | 接收短信 |
| 407 | LOW_BALANCE | 已收到短信，但余额不足以支付。 | 接收短信 |
| 410 | ORDER_CLOSED | 订单已关闭，不可继续使用。 | 接收短信 |
| 500 | SMS_FETCH_FAIL | 未能获取短信。 | 接收短信 |
| 501 | SERVER_FAIL | 服务器未能处理请求。 | 接收短信, 当前订单, 清除短信, 停止接收短信, 屏蔽号码 |
| 503 | SERVER_BUSY | 服务器负载过高，请稍后再试。 | 接收短信, 当前订单, 停止接收短信, 取消订单, 屏蔽号码 |
| 405 | INVALID_NUMBER_FORMAT | 号码格式不正确 | 号码状态 |
| 406 | ORDER_NOT_FOUND | 订单 ID 格式不正确或未找到。 | 号码状态, 停止接收短信, 取消订单, 屏蔽号码 |
| 500 | SERVER_ERROR | 服务器内部错误，说明可能包含诊断详情。 | 号码状态 |
| 501 | — | 服务器未能处理请求。 | 号码状态 |
| 503 | — | 服务器负载过高，请稍后再试。 | 号码状态 |
| 504 | — | av2.resp.504.desc：原始文档未提供此响应的完整说明。 | 号码状态 |
| 404 | NO_SMS_TO_CLEAN | 尚未收到短信，或有待付费短信。 | 清除短信 |
| 406 | ORDER_NOT_FOUND | 未找到订单。 | 清除短信 |
| 503 | SERVER_BUSY | 尚未收到短信，或有待付费短信。 | 清除短信 |
| 501 | SERVER_BUSY | 服务器未能处理请求。 | 取消订单 |
| 405 | INVALID_PARAMS | 号码格式不正确 | 屏蔽号码 |