错误处理

Portal API 失败时返回统一 JSON envelope。业务代码应先判断 HTTP 状态，再读取 error.code，不要依赖中文消息文本做分支。

错误结构

{
  "error": {
    "code": "invalid_input",
    "message": "Request body is invalid",
    "details": {},
    "requestId": "request-id-for-support"
  }
}

details 和 requestId 可能省略。发生问题时请保留请求 ID、时间、操作页面和订单/申请编号，不要提交 API Key、Cookie、验证码或完整手机号。

错误代码

code	常见 HTTP 状态	处理建议
invalid_input	400	修正字段、范围或格式后再提交
unauthorized	401	重新登录；模型请求则检查 API Key
forbidden	403	当前账号或角色无权执行该操作
not_found	404	检查资源 ID，避免跨用户访问
conflict	409	刷新最新状态，确认是否已有进行中的命令
rate_limited	429	等待限制窗口后重试，不要高频轮询
job_unavailable	503	后台恢复任务不可用，保留当前业务记录
payment_unavailable	503	在线支付尚未开通，钱包读取仍可用
internal	500 / 503	使用请求 ID 排查；不确定远端结果时不要盲重试变更命令

可以重试吗

读取模型、余额、Key 列表和用量失败时，可以稍后重试。创建 Key、启动支付、确认付款、额度发放、账号停用或发票开具等变更命令可能已经在远端提交；遇到超时或 manual_review 时，应先刷新状态或交由 Admin 处理。

部分数据不可用

账户概览会按字段标记部分失败。例如用量统计失败时，余额和 Key 数量仍可能正常显示。页面同时展示网关获取时间，未成功取得的数据不会用本地旧值替代。