错误

此页面规范由统一推理管道生成的 HTTP 响应和 OpenAI 风格的错误主体。用于前端/后端集成、监控和警报路由。

---

1. 错误对象模式（OpenAI 风格）

所有错误返回 application/json 正文：

{
  "error": {
    "type": "invalid_request_error | rate_limit_exceeded | service_unavailable | timeout | internal_error | server_error",
    "code": "unsupported_provider | executor_binding_validation_failed | model_not_found | invalid_api_key | permission_denied | rate_limit_exceeded | model_fetch_error | internal_error | service_unavailable | orchestrator_missing | closed_source_service_unavailable | timeout",
    "message": "人类可读的描述",
    "param": "可选，当某个特定字段无效时",
    "provider": "可选，涉及的提供者/模型",
    "request_id": "可选，用于追踪"
  }
}

---

2. 状态码矩阵（概览）

HTTP	来源（入口）	error.type	error.code	典型触发原因	回退说明
400 Bad Request	UnifiedInferenceService	invalid_request_error	unsupported_provider	请求明确选择了不支持的提供者	客户端错误 — 无回退
400 Bad Request	ExecutorBindingValidatorService	invalid_request_error	executor_binding_validation_failed	API 密钥绑定到不兼容的执行器类型	停止并修复绑定
400 / 404	ExecutorBindingValidatorService	invalid_request_error	model_not_found	验证期间未找到模型信息	检查模型配置/绑定
401 Unauthorized	SimpleErrorClassifier	invalid_request_error	invalid_api_key	认证失败 / API 密钥无效	更新客户端凭证
403 Forbidden	SimpleErrorClassifier	invalid_request_error	permission_denied	用户绑定/权限检查失败	无回退
404 Not Found	SimpleErrorClassifier	invalid_request_error	model_not_found	模型不存在或无法访问	确认模型 id
429 Too Many Requests	sendErrorResponse / SimpleErrorClassifier	rate_limit_exceeded	rate_limit_exceeded	超出速率限制或配额	可回退
500 Internal Server Error	UnifiedInferenceService	internal_error	model_fetch_error	从存储获取模型列表失败	基础设施调查
500 Internal Server Error	sendErrorResponse	server_error	internal_error	未分类的内部错误	可回退
502 Bad Gateway	sendErrorResponse	service_unavailable	service_unavailable	执行器或下游失败（关键字匹配）	可回退
503 Service Unavailable	UnifiedInferenceService	service_unavailable	orchestrator_missing / closed_source_service_unavailable	未注入编排器 / 缺少闭源 gRPC 客户端	检查依赖；重试/回退
503 Service Unavailable	sendErrorResponse	service_unavailable	service_unavailable	类似 “no healthy executors”、“service unavailable” 的关键字	回退到其他提供者
504 Gateway Timeout	sendErrorResponse	timeout	timeout	执行器选择或下游调用超时	可回退

---

3. 主要来源与映射逻辑

3.1 UnifiedInferenceService

• 遇到 HttpException 时，透传状态和正文。

• validateOrchestrator 缺失 → 503 service_unavailable（orchestrator_missing）。

• 缺少闭源 gRPC 客户端 → 503 service_unavailable（closed_source_service_unavailable）。

• 不支持的提供者 → 400 invalid_request_error（unsupported_provider）。

• getModelList 存储调用失败 → 500 internal_error（model_fetch_error）。

• sendErrorResponse 使用 mapErrorToHttpStatus（关键字启发式）：

  • 包含 “no healthy executors” / “service unavailable” → 503

  • 包含 “rate limit” / “quota” → 429

  • 包含 “timeout” → 504

  • 包含 “invalid” / “bad request” → 400

  • 否则 → 500

3.2 ExecutorBindingValidatorService

• 在验证失败时，构建与 OpenAI 兼容的错误主体并抛出 HttpException。

• 典型情况：缺少模型绑定；执行器类型不匹配。

3.3 SimpleErrorClassifier & Formatter

• 对于 HttpException，保留原始状态；映射到 UnifiedErrorType：

  • 401 → invalid_api_key

  • 403 → permission_denied

  • 404 → model_not_found

  • 429 → rate_limit_exceeded

  • 其他 4xx → invalid_request

  • 任何 5xx → internal_error

• 对于通用错误，通过关键字分类（与上述相同的启发式），然后生成 OpenAI 风格的主体。

---

4. 回退策略

shouldAttemptFallback 将以下 HTTP 状态视为可回退：500、502、503、504、429。

此外，如果错误消息包含任何：

TIMEOUT、CONNECTION_ERROR、SERVICE_UNAVAILABLE、
RATE_LIMITED、EXECUTOR_UNAVAILABLE、LOAD_BALANCING_FAILED

则触发回退逻辑（根据策略尝试其他提供者/执行器）。

客户端指南：前端/SDK 应检测这些状态/代码并在适当情况下应用带抖动退避的重试和提供者/模型回退。

---

5. 监控与告警（最小清单）

• 按状态、error.type、error.code、提供者、模型、区域进行分组。

• 为以下项创建 SLO：成功率、P50/P95 延迟、回退成功率、超时比例。

• 对持续的 5xx/service_unavailable/timeout 激增以及 “no healthy executors” 设置高优先级告警。

• 单独跟踪 429（配额/速率策略）并向用户展示可操作的建议。

---

6. 示例错误主体

400 · unsupported_provider

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_provider",
    "message": "提供者 'acme-llm' 不受支持。"
  }
}

401 · invalid_api_key

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "message": "API 密钥无效或已过期。"
  }
}

429 · rate_limit_exceeded

{
  "error": {
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "message": "超过速率限制。请稍后重试。"
  }
}

503 · no healthy executors

{
  "error": {
    "type": "service_unavailable",
    "code": "service_unavailable",
    "message": "区域 'us-east' 中没有可用的健康执行器。"
  }
}

504 · timeout

{
  "error": {
    "type": "timeout",
    "code": "timeout",
    "message": "下游调用在 30 秒后超时。"
  }
}