错误码与恢复
HTTP 状态、稳定错误码、请求编号和有限重试。
错误结构为：
{"error":{"code":"ADMIN_PERMISSION_DENIED","message":"BI reader role is required","request_id":"请求编号","details":null}}以 HTTP 状态和 error.code 做程序分支。message 仅供诊断，不作为判断条件。响应通常带 X-Request-Id、X-Platform-Version 和 X-Platform-Revision；排查时提供请求编号、接口路径、查询日期和发生时间，不提供 Key、令牌或密码。
| HTTP | 错误码 | 处理 |
|---|---|---|
| 401 | ADMIN_AUTH_REQUIRED | 缺少凭据；配置专用 Key，或兼容登录获取 Bearer |
| 401 | ADMIN_AUTH_INVALID | Key 到期、撤销、无效、混用凭据或账号停用；Key 模式立即停止。兼容密码模式最多重新登录一次 |
| 403 | ADMIN_PERMISSION_DENIED | 当前账号无 BI 权限，停止并联系平台管理员 |
| 403 | ADMIN_PASSWORD_CHANGE_REQUIRED | 完成首次改密后重新登录 |
| 422 | ADMIN_PASSWORD_POLICY | 新密码不符合规则，不自动重试 |
| 422 | VALIDATION_ERROR | 修正日期、分页、币种、枚举、重复或未知参数 |
| 409 | ADMIN_ACCOUNT_CONFLICT | 当前认证方式无法改密；联系平台管理员 |
| 429 | RATE_LIMITED | 遵守 Retry-After，有限退避 |
| 503 | RATE_LIMITED | 报表等待／执行超时，缩小查询窗口，按 Retry-After 重试 |
| 503 | BI_AUDIT_UNAVAILABLE | Key 校验／审计存储不可用；有限重试，持续失败联系平台管理员 |
| 503 | ADMIN_AUTH_NOT_CONFIGURED | 认证服务未配置，停止并联系平台管理员 |
| 500 / 503 | INTERNAL_ERROR | 保存请求编号，有限重试并报告持续异常 |
网关可能返回非 JSON 的 404、413、502、503、504：分别检查地址、请求体大小或服务可用性。未知错误码保留状态和请求编号，不解析供应商错误原文。示例客户端每次读取最多 3 次尝试，Key 模式遇 401 停止，兼容密码模式 401 最多重新登录一次；429、502、503、504 及网络错误有限重试，等待超过 60 秒的建议由调度器安排下一轮。
查询不会执行支付、退款、AI 生成或任何业务重放。失败恢复只重读接口，不提交资金操作。同步任务失败时保留上一版已完成快照并标记更新时间，不用空结果覆盖失败的查询。