全局状态码与错误字典
OmniCortex 采用标准化、双向对齐的错误处理机制。在协议层面，网关对外 100% 兼容 OpenAI 错误响应规范（{"error": {...}}），确保现存业务系统的 SDK、自动化客户端与上层 AI 应用能够无缝捕获与识别异常；在治理与可观测性层面，网关为每个错误响应注入全局追踪凭证（event_id）与链路归因标识（is_omnicortex_error），实现“客户端无痛接入、运维侧秒级定界”。
统一错误响应结构与契约规范
1. 契约兼容设计
无论业务端使用的是官方 OpenAI Python SDK、Node.js SDK、LangChain 还是原生 HTTP 客户端，当请求被网关策略阻断或上游模型发生故障时，均会收到符合标准的 JSON 错误响应。业务代码可直接使用标准异常捕获块（如 Python 的 except openai.APIError as e:）读取 e.message、e.code 与 e.type，无需修改任何解析逻辑。
标准错误响应报文范例：
json
{
"error": {
"message": "Model 'gpt-4o' is not permitted by Virtual Key 'app-crm-backend'. Allowed models: ['qwen-max', 'deepseek-v3'].",
"type": "permission_denied",
"code": "model_not_allowed",
"param": "model",
"event_id": "evt_01j8m4kzp3q5e8r1n7v9"
},
"is_omnicortex_error": true,
"status_code": 403,
"event_id": "evt_01j8m4kzp3q5e8r1n7v9",
"extra_fields": {
"provider": "openai",
"model_requested": "gpt-4o",
"request_type": "chat_completion"
}
}2. 错误响应字段语义与排障价值
| 字段名称 | 归属层级 | 业务应用与排障语义 | 治理价值与客户端适配 |
|---|---|---|---|
error.message | 协议标准 | 结构化的人类可读错误描述，清晰标明故障根因与上下文信息 | 业务层可直接展示在前端界面或写入告警群，便于研发人员快速感知问题 |
error.code | 协议标准 | 机器可读的全局唯一细分错误码（如 model_not_allowed） | 供业务系统在 SDK 异常处理中做精确的 switch-case 条件分支调度 |
error.type | 协议标准 | 错误大类标识（如 invalid_request_error、permission_denied） | 对应主流 SDK 内置的特定异常类层级，保持语言生态标准语义 |
error.param | 协议标准 | 触发校验失败或策略阻断的具体请求参数名（如 model、stream） | 快速指引调用方修正请求 Payload 中的非法字段 |
is_omnicortex_error | 网关增强 | 标识该异常是由 OmniCortex 网关策略拦截（true）还是上游供应商透传（false） | 核心定界依据：true 排查网关密钥与防线配置，false 排查供应商账号状态 |
event_id | 网关增强 | 网关为该次请求生成的全局唯一追踪流水 ID（全链路唯一） | 贯穿网关内核、异步流式帧与审计日志，可在控制台日志中一键穿透定位 |
extra_fields | 网关增强 | 包含发生异常时尝试命中的供应商标识、请求类型与模型版本 | 辅助架构师与运维人员复盘多云路由决策与容灾降级调度全历程 |
网关全链路错误分流与自愈流转拓扑
在请求的完整生命周期中，错误可能在不同的处理阶段被捕获或自愈。理解错误发生的层级是高效定位问题的核心关键：
🛡️
标准状态码闭环 · 自动容灾调度OmniCortex 全链路错误拦截与自愈生命周期
从入口协议解析、治理安全防线到多通道算力容灾的完整分流闭环
🚪
阶段 1 · 协议校验与身份门控 (Ingress & Auth)
校验请求报文格式、提取 Bearer 密钥、核验密钥启用态与有效期
400 Bad Request · 401 Unauthorized
✓ 身份认证合法 ➔ 进入策略与安全检查
🚦
阶段 2 · 访问策略、流控配额与安全防线 (Policy & Guardrails)
检查模型准入名单、RPM/TPM 限流计数、周期预算配额、输入内容安全检测
403 Forbidden · 429 Too Many Requests
✓ 治理策略合规 ➔ 派发至算力路由层
⚡
阶段 3 · 上游算力调度与容灾自愈 (Upstream Routing & Resilience)
首选供应商若遭遇网络断流、5xx 或超时，网关内核自动触发跨模型阶梯容灾降级
自愈成功 200 OK / 耗尽 503
全局 HTTP 状态码全景对照表
网关严格遵循标准 HTTP 状态码语义，将网关策略与上游供应商状态进行规范化归类：
| HTTP 状态码 | 英文状态标识 | 产生层级 | 典型触发场景 | 是否触发容灾降级 |
|---|---|---|---|---|
200 | OK | 全链路 | 模型推理成功，返回完整的非流式 JSON 报文或握手建立 SSE 持续流 | - |
400 | Bad Request | 网关 / 上游 | 请求体 JSON 格式损坏、必需参数缺失、输入内容触发安全防线阻断、上下文超长 | 否 |
401 | Unauthorized | 网关 | 未提供 API Key、虚拟密钥不存在、密钥处于停用状态、密钥已过期 | 否 |
403 | Forbidden | 网关 | 虚拟密钥未被授权访问请求的目标模型（不在关联访问策略集的模型白名单中） | 否 |
404 | Not Found | 网关 | 调用的网关接口路径不存在、请求的模型标识既非物理模型也未配置别名重定向 | 否 |
429 | Too Many Requests | 网关 / 上游 | 突破团队或虚拟密钥的瞬时 RPM 限流、TPM 限流，或周期配额预算已耗尽 | 上游 429 可触发 |
500 | Internal Server Error | 网关 | 网关服务自身运行时非预期 Panic、底层持久化存储读写不可用 | 否 |
502 | Bad Gateway | 网关（代理层） | 上游模型供应商网络不通、连接被重置、上游反向代理返回无法解析的非 JSON 报文 | 是 |
503 | Service Unavailable | 网关 | 首选供应商及其配置的多级容灾备选链路（Fallbacks）均尝试失败且已全部耗尽 | 是（兜底终态） |
504 | Gateway Timeout | 网关（超时控制） | 上游模型供应商在网关设定的超时窗口内未吐出首字，或流式帧间隔超时断流 | 是 |
细分业务错误码字典 (Error Code Reference)
在 error.code 中，网关输出细粒度的机器码，便于调用端编写防御代码：
1. 身份认证与权限管理 (authentication_and_authorization)
细分错误码 (error.code) | 对应 HTTP | 错误详细原因 | 推荐处置方案与自愈路径 |
|---|---|---|---|
invalid_api_key | 401 | 请求头中的 API Key 字符串在网关数据库中未检索到，或已被管理员彻底删除 | 检查请求头 Authorization: Bearer <token> 是否准确复制，或重新生成密钥 |
virtual_key_expired | 401 | 虚拟密钥到达了创建时设定的绝对失效时间戳（expires_at） | 联系组织管理员在「虚拟密钥」管理界面延长有效期，或签发新密钥 |
virtual_key_disabled | 401 | 虚拟密钥在管理控制台中被管理员手动置为“禁用”状态 | 联系管理员在控制台启用该密钥，确认是否有合规停用原因 |
model_not_allowed | 403 | 请求的模型不在当前虚拟密钥所绑定的「访问策略集 (Access Profile)」白名单中 | 在控制台将目标模型勾选加入策略集，或更换已获授权的可用模型 |
team_access_denied | 403 | 当前密钥试图跨团队访问其他业务团队所属的模型通道或私有算力资源 | 检查密钥归属团队，确保各业务线在各自团队组织架构内发起调用 |
2. 流量治理与配额控制 (governance_and_rate_limits)
细分错误码 (error.code) | 对应 HTTP | 错误详细原因 | 推荐处置方案与自愈路径 |
|---|---|---|---|
rpm_limit_exceeded | 429 | 当前请求触发了密钥或所属团队配置的每分钟请求数（RPM）滑动窗口上限 | 客户端应在业务层加入指数退避重试，或在控制台按需调大瞬时 RPM 阈值 |
tpm_limit_exceeded | 429 | 请求携带的 Token 计数与近期消耗累积超出了每分钟 Token 数（TPM）上限 | 评估是否为批量非实时计算任务，建议错峰调度或申请上调吞吐阈值 |
budget_quota_exhausted | 429 | 当前虚拟密钥或所属团队的自然月/自定义周期配额预算已完全消耗殆尽 | 管理员可在控制台针对该密钥执行「紧急调额 (Budget Override)」立即恢复服务 |
3. 安全围栏与合规审计 (guardrails_violations)
细分错误码 (error.code) | 对应 HTTP | 错误详细原因 | 推荐处置方案与自愈路径 |
|---|---|---|---|
guardrail_input_blocked | 400 | 用户输入的 Prompt 命中了企业防线规则包中的违规词库或 Prompt 注入特征 | 检查输入内容合规性，或在控制台「安全拦截日志」中复盘命中的具体规则 |
guardrail_pii_blocked | 400 | 输入内容中包含身份证号、银行卡等个人隐私信息，且防线动作配置为“阻断” | 若业务需允许传输，可将防线策略动作由“阻断”调整为“脱敏掩码（Masking）” |
guardrail_hallucination_blocked | 400 | 模型输出内容经过幻觉检测引擎裁定，与指定基准上下文背离并触发拦截 | 调整提示词约束，或优化防线对幻觉判定的置信度阈值 |
4. 模型路由与调度容灾 (routing_and_fallbacks)
细分错误码 (error.code) | 对应 HTTP | 错误详细原因 | 推荐处置方案与自愈路径 |
|---|---|---|---|
model_not_found | 404 | 请求中指定的模型名在全局模型目录中不存在，且未配置别名重定向规则 | 检查模型标识拼写，或在「模型资产目录」中确认该模型是否已注册上线 |
all_fallbacks_exhausted | 503 | 高可用容灾核心终态：首选模型故障，且备选降级列表中所有供应商通道均尝试失败 | 检查上游供应商的物理网络连通性、账号余额，或补充更多异构可用备用通道 |
provider_timeout | 504 | 上游模型供应商推理响应超时（超过了网关或策略配置的响应等待窗口） | 检查上游云服务实时健康态，或针对长文本推理场景放宽网关超时时间 |
context_length_exceeded | 400 | 请求的总 Token 长度超出了目标模型底层硬性支持的最大 Context Window | 启用网关的自动上下文滑动窗口修剪策略，或切换至大长文本模型 |