可靠性

错误码与重试

所有错误使用一致的 JSON 结构。客户端应同时判断 HTTP 状态和 error.code，不要依赖 message 文案编写业务逻辑。

错误响应格式

{
  "success": false,
  "error": {
    "code": "NO_FREE_PHONES",
    "message": "该线路暂时无号码，请稍后重试"
  }
}

错误码	HTTP	处理建议
API_UNAUTHENTICATED	401	API Key 缺失、无效或已撤销。更新认证信息后再请求。
INSUFFICIENT_WALLET_BALANCE	402	可用余额不足。充值后使用新的业务请求重试。
VALIDATION_ERROR	422	参数格式不正确。检查 JSON、字段类型与 slug。
BAD_COUNTRY	422	国家代码无效。使用国家列表中的代码。
BAD_OPERATOR	422	线路代码无效。选择当前可用线路或 any。
NO_PRODUCT	422	服务代码无效。使用服务列表中的代码。
RATE_LIMITED	429	请求过于频繁。等待后使用退避策略重试。
NO_FREE_PHONES	409	当前组合没有可用号码。稍后重试或更换国家、线路。
ACTIVE_ORDER_EXISTS	409	已有订单处理中。先查询、完成或取消当前订单。
ORDER_NOT_FOUND	404	订单不存在或当前账户无权访问。
SMS_CODE_REQUIRED	409	尚未收到验证码，不能完成订单。
ORDER_NOT_CANCELABLE	409	订单当前状态不允许取消。
NUMBER_SERVICE_UNAVAILABLE	502	号码服务暂时不可用。稍后安全重试。