ZTProxy 错误响应格式和排查建议。基础地址：https://backend.ztproxy.net/api

错误处理

ZTProxy API 使用 HTTP 状态码和 JSON 响应体共同表示请求结果。业务失败通常会返回非 0 code，并带有中文 message 或 msg。

常见格式

{
  "code": 401,
  "message": "未提供认证令牌",
  "data": {}
}

{
  "code": 400,
  "msg": "目标用户余额不足",
  "data": {}
}

FastAPI 参数校验错误可能使用标准 detail 字段：

{
  "detail": [
    {
      "loc": ["body", "duration"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

HTTP / Code	提示	含义	处理方式
`401`	`未提供认证令牌`	未携带 Bearer Token。	添加 `Authorization: Bearer <token>`。
`401`	`无效的认证令牌`	Token 无效或过期。	重新登录。
`401`	`邮箱或密码错误`	登录失败。	检查用户名和密码。
`403`	`没有创建用户的权限`	当前用户无权创建用户。	使用代理商账号。
`403`	`只能为下级用户创建订单`	代理商为非下级用户下单。	使用该代理商名下的用户。
`403`	`仅代理商账号可以操作下属用户`	使用了非代理商账号调用代理商下属账号管理接口。	使用代理商 token。
`403`	`只能操作当前代理商的直属下属用户`	目标账号不属于当前代理商。	检查 `user_id` 和账号归属。
`403`	`仅代理商账号可以查看下属用户`	非代理商账号调用下级账号列表接口。	使用代理商 token。
`400`	`用户名已存在`	编辑下级用户账号时用户名重复。	换用未占用用户名。
`400`	`status 只能是 active、disabled 或 deleted`	下级账号列表状态筛选值不合法。	使用合法的 `status` 参数或移除筛选。
`400`	`余额不足`	下级用户余额扣减后会小于 0。	减少扣减金额或先充值。
`400`	`目标用户余额不足`	余额低于订单金额。	充值或降低订单金额。
`404`	`用户不存在`	目标用户不存在。	检查 `userId`。
`500`	`创建订单失败`	创建订单时后端异常。	检查参数后重试；持续失败请联系支持。

参数校验、权限、余额不足等错误不要直接重试，应先修正请求或账号状态。
Token 错误时重新登录后重试一次。
网络错误或 5xx 可使用指数退避重试。
标准静态订单创建成功响应会包含 orderNo / order_no 和 queued: true。拿到订单号后不要重复提交，应查询订单列表等待最终状态。
如果网络超时导致没有拿到响应，应先按请求时间、目标用户和产品查询订单列表，确认是否已生成订单，避免重复下单。