错误处理

核心 OpenAI 兼容接口（/v1/chat/completions、/v1/images/generations、/v1/videos 等）在发生错误时，统一返回如下结构：

{
  "error": {
    "message": "error description",
    "type": "error_type"
  }
}

错误类型

type	含义	触发场景
authentication_error	鉴权失败	未携带 API Key、Key 无效
access_denied_error	访问被拒绝	中继功能被关闭、模型不在 Key 白名单内
invalid_request_error	请求非法	请求体格式错误、缺少必填字段、缺少 prompt、缺少视频 id 等
quota_exceeded_error	额度不足	用户/API Key 额度用尽，或订阅套餐不可用
image_generation_error	图像生成失败	上游未返回可用的图片
chatnio_api_error	通用错误（默认）	未显式指定类型时的兜底

HTTP 状态码

状态码	说明
200	成功
401	未授权（鉴权中间件直接拦截，返回 { code, message }）
503	核心接口的业务错误（sendErrorResponse 固定返回 http.StatusServiceUnavailable）

注意

核心中继接口的「业务错误」与「HTTP 状态码」并非一一对应：即使返回 503，真正的错误信息在响应体 error.type 与 error.message 中。请以响应体为准。

鉴权错误

鉴权会在进入业务逻辑前直接拦截，其响应格式与核心接口不同：

{
  "code": 401,
  "message": "Access denied. Please provide correct api key."
}

常见场景：

• IP 在黑名单 → { "code": 403, "message": "ip in black list" }
• API Key 无效 → { "code": 401, "message": "Access denied. Please provide correct api key." }

流式请求中的错误

对于 stream: true 的流式请求，若在流传输过程中发生错误，网关会：

1. 发送一个带有 error 字段的流式块（choices[0].delta.content 为该错误的文本描述）；
2. 立即结束流。

因此客户端在解析 SSE 时，除 finish_reason 外，还应关注每个 chunk 是否携带 error 字段。

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion.chunk",
  "created": 1700000000,
  "model": "gpt-3.5-turbo",
  "choices": [
    {
      "index": 0,
      "delta": { "content": "quota exceeded" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 },
  "error": { "message": "quota exceeded", "type": "quota_exceeded_error" }
}