错误码
先区分响应层级
| 端点 / 阶段 | 形态 |
|---|---|
REST 业务接口（如 /v1/api/invoke） | 通过鉴权后，HTTP 200 + {code, message, data}，code≠200 即失败 |
受保护 /v1/** 的鉴权 / 准入拒绝 | HTTP 401 / 403 / 503 + {error, error_description}，见下表 |
MCP /v1/mcp 协议处理 | JSON-RPC result 或 error；不能按 REST 的顶层 code 判断 |
| MCP 工具执行 | result.isError: true 表示工具失败；content 文本内为 {ok: false, message, code?} |
OAuth 协议端点 /oauth/** | 使用 {error, error_description}；常见 HTTP 400 / 429，权益拒绝与暂不可校验另见下文 |
MCP 准入与临时故障
MCP 要求当前租户超级管理员（SUPERADMIN）、租户启用、主套餐 ACTIVE，以及同租户有效 MCP 订阅权益（主套餐明确包含，或另行购买）。 以下 HTTP 状态发生在进入工具之前，不等于工具内业务码：
| HTTP / error | 含义 | 处理 |
|---|---|---|
401 invalid_token | 凭证缺失 / 无效，或当前身份已不满足条件（超级管理员降权、员工禁用 / 离职、租户禁用等）；携 WWW-Authenticate | 首次连接按 OAuth 流程授权；已有连接先核实身份和租户状态，不能只反复授权 |
403 access_denied | 在授权预检、换 token、refresh 或调用补验时发现 MCP 权益不满足，如主套餐非 ACTIVE 或不在有效期、未包含且未购买 MCP、到期 / 取消后无其他有效权益 | 检查同一租户的主套餐与权益；需要购买时到主站 /service-subscription?tab=market，恢复条件后再尝试 |
503 temporarily_unavailable | 身份服务故障、MCP 请求侧 Redis 无法安全读写收费缓存、需要远程核验时 PM 不可用，或收费配置无法安全校验；Retry-After: 5 | 等待至少 5 秒后再检查；持续失败联系运维，不重复购买、不自动重新授权 |
授权同意页继续区分 INACTIVE（条件不满足）与 UNAVAILABLE（暂不可校验）；两者都不能继续同意，后者不代表未购买。
授权码交换及刷新也会校验身份与权益：身份已失效可返回 invalid_grant；权益不满足返回 403 access_denied，身份 / 收费核验服务故障返回 503 temporarily_unavailable。
这与已有 MCP 请求的身份拒绝返回 401 不同，不能一律解释为“令牌过期”。
HTTP 403 也不必然都是订阅问题，管理操作等其他端点仍需按其响应说明检查权限。
签发后辅助缓存写入例外：首次换 token / refresh 的实时收费核验已成功、token 已签发后，仅辅助 paid marker 写入 Redis 失败时记录日志，仍返回已签发 token，不改报 503。此时授权码已消费或 refresh 已轮换，不应重放旧凭证。marker 缺失时后续首次 MCP 请求补验；请求侧 Redis 读写故障仍返回 503，不能免费放行。
收费缓存与拒绝时机
- OAuth 授权页面预检、首次授权码换 token、每次 refresh 仍远程核验 PM；access token 默认 7200 秒（可配置），不是服务端定时 refresh。
- 正常 MCP 调用命中有效收费缓存时不查询 PM。token 的通过结果仅缓存至该 token 自身到期，命中不续期；旧 token / 缓存丢失首次使用补验一次，成功后不改变原到期时间。
- 收费到期 / 取消后，已签发 token 最长延迟一个 access token 有效期才拒绝；AppKey 没有 refresh，固定 2 小时收费缓存，命中不续期，到期后下次调用补验。
- 已有可读取的有效收费缓存不受 PM 故障影响；但每次仍校验凭证与当前管理员 / 租户，身份链故障仍可能返回 503。MCP 请求侧 Redis 无法核验缓存或需要补验时 PM 不可用，不能降级免费放行。
- 收费缓存不豁免撤销授权、管理员降权、员工或租户禁用。这些身份拒绝仍按 401 处理，而非等待收费缓存到期。
缓存只是收费核验时机，不延长 min(mainEnd, paidEnd) 对应的权益截止日期。详见认证与授权。
即使关闭权益校验配置，也不会免费放行 MCP，而是以 503 拒绝。上述 MCP 权益检查不改变 REST invoke 的原有准入规则。 任何阶段遇到写操作超时或结果不明，先查业务状态，禁止盲目重发。
业务错误码（92000-92399）
| 错误码 | 说明 | 可重试 |
|---|---|---|
| 92001 | 开放应用不存在 | 否 |
| 92002 | 客户端回调地址不合法（仅收 https 与本机回环 http） | 否 |
| 92003 | 客户端注册信息不合法 | 否 |
| 92101 | 访问凭证无效 | 否（重新授权/检查凭证） |
| 92102 | 授权请求不存在或已过期（同意页停留超 10 分钟） | 回客户端重新发起 |
| 92103 | 授权范围不合法 | 否 |
| 92104 | 授权记录不存在 | 否 |
| 92105 | 未获取到登录用户信息 | 重新登录后重试 |
| 92106 | AppKey 不存在 | 否 |
| 92201 | 接口未登记或已停用 | 否（联系管理员启用） |
| 92202 | 超出凭证授权范围 | 否（重新授权勾选相应范围） |
| 92203 | 上游服务调用失败 | 读操作可重试；写操作先查询处理结果，禁止盲目重试 |
| 92204 | 该员工无此接口的功能权限（主站模块权限缺失） | 否（联系管理员分配权限，变更 ≤1 分钟生效） |
| 92205 | 写操作处理超时，结果未知：该操作可能仍在后台执行 | 否（先查询确认结果，不要直接重试） |
| 92301 | 请求过于频繁 | 是（退避后重试） |
| 92302 | 该请求正在处理中，请勿重复提交 | 等待原请求完成并核实结果，不自动重发 |
92205 与 92203 的区别
直通转发对下游的连接超时为 5 秒、读超时为 30 秒。
92205只出现在写接口：请求已送达下游，但 30 秒内没等到响应。下游线程不会因此中断， 写操作可能已经或仍将完成。它不是「失败」，而是「结果未知」。92203是确定的调用失败（连接不上、响应格式异常等），以及读接口的超时。读操作可重试； 写操作仍建议先查询结果。
收到 92205 后，先按业务单号、名称等查询数据是否已写入（导入任务查 import-result），
确认未生效再由用户决定是否补做。此时立即重发相同请求会收到 92302，见下节。
批量写入的拆分方式见批量操作。
92302 与 92301 的区别
92301 是频率超限，需要退避；92302 不是限流，而是写接口的防重复提交——
你有一笔参数完全相同的写请求正在处理中，尚未返回。
- 只作用于写接口，读查询（
page/list/detail等）不受此限制，可放心并发 - 判定依据是「凭证 + 接口编码 + 请求参数（query 与 body）」三者全同；参数不同即视为不同请求。 参数按收到的原样计算摘要，不保证键顺序不同的两份 JSON 被视为相同——重发时请原样使用同一份参数
- 锁在前一次请求结束时立即释放，顺序发起的相同请求不受影响；锁的兜底有效期为 30 秒， 仅用于进程异常退出时自动解除，执行期间不续期
- 写接口超时返回
92205时例外：锁不释放，而是续持 120 秒，让紧随其后的相同请求收到92302，避免与仍在执行的原请求并发、重复写入 - 防重锁依赖 Redis；Redis 不可用时放行请求（不加锁、不拒绝），此时不再有并发防重保护
此机制不是业务幂等：顺序重试、进程崩溃、网络超时后，下游可能已经提交数据。 写请求遇到不确定结果时应先查询业务状态，不要自动重发。
碰到它通常意味着你的重试逻辑在前一次尚未返回时就重发了。正确做法是等前一次 返回，而不是退避后盲目重试——重试一个仍在执行的写操作，本就是这道闸要防的事。
直通调用中下游业务失败时，code 透传下游业务码（非 92xxx 段），message 为下游描述。
OAuth 协议错误（error 字段）
| error | 场景 |
|---|---|
invalid_request | 参数缺失/不合法、批量请求、限流触发（429） |
invalid_client | client_id 未知 |
invalid_grant | 授权码 / 刷新令牌无效、过期、已撤销、重放，或交换 / 刷新时绑定身份已失效（统一不区分原因） |
unsupported_grant_type / unsupported_response_type | 仅支持 authorization_code + refresh_token / code |
invalid_scope | scope 含平台词汇外条目 |
access_denied | 用户在同意页拒绝，或 MCP 权益准入不满足；按发生阶段和 HTTP 状态处理 |
temporarily_unavailable | 身份、MCP 请求侧 Redis、收费配置或需要远程核验时的 PM 暂不可用（503）；不包括成功签发后的辅助 paid marker 写入失败。等待恢复，不视作未购买或令牌失效 |
invalid_target | resource 参数指向未知资源（RFC 8707） |
invalid_client_metadata / invalid_redirect_uri | 动态注册元数据/回调地址不合法（RFC 7591） |
invalid_token | 受保护资源的 Bearer 凭证缺失或无效（RFC 6750，随 401） |
安全说明：授权码 / 刷新令牌无效、过期、撤销、重放或绑定身份已失效，统一返回 invalid_grant，不区分具体原因以防探测；不要把身份 / 权益服务故障混同为此类错误。