本文介绍调用云信服务端接口以及使用网易云信大模型 API 过程中出现的各类错误码及错误信息，您可以参考详细描述排查对应的问题。

网关对外主要返回两类错误：

• 网关自行生成的标准错误。
• 原样返回的错误。

标准错误格式

json{
  "error": {
    "type": "authentication_error",
    "message": "invalid api key",
    "request_id": "req_abc123"
  }
}

字段说明：

字段	类型	说明
error.type	string	错误类型
error.message	string	错误信息
error.request_id	string	请求 ID

当前常见 error.type：

• invalid_request_error
• authentication_error
• not_found
• proxy_error
• upstream_timeout
• internal_error
• not_implemented

网关生成错误

鉴权错误

HTTP	type	message	说明
401	authentication_error	missing api key	缺少 Bearer Key
401	authentication_error	invalid api key	key 不存在、格式非法、禁用、过期、所属 app 禁用等
403	authentication_error	ip not allowed for this key	IP 白名单不匹配
403	authentication_error	model not allowed for this key	模型白名单不匹配
500	internal_error	internal error	鉴权内部故障

请求错误

HTTP	type	message	说明
400	invalid_request_error	failed to read request body	请求体读取失败
400	invalid_request_error	invalid request body	请求体不是合法 JSON，或字段类型非法
400	invalid_request_error	callback_url_too_long	callback_url 超长
400	invalid_request_error	callback_url_invalid	callback_url 非法
400	invalid_request_error	callback_url_scheme_forbidden	callback_url 协议不允许
400	invalid_request_error	callback_url_private_ip	callback_url 命中危险裸 IP

任务与路由错误

HTTP	type	message	说明
404	not_found	not found	路径不存在
404	not_found	task not found	任务不存在或不属于当前 app
501	not_implemented	task-op endpoints available in next release	预留 task-op 端点未实现

代理与内部错误

HTTP	type	message	说明
502	proxy_error	no active channel	当前没有可用通道
502	proxy_error	upstream error	服务暂时不可用
504	upstream_timeout	upstream timeout	请求超时
500	internal_error	internal	本地写库、状态推进等内部错误

原样返回的错误

部分错误会按原始状态码和响应体返回：

• HTTP 状态码透传
• 响应 body 原样透传
• 不再包装成 error.type/error.message/request_id

常见场景：

• 参数校验失败
• 权限错误
• 资源不存在
• 限流或内部错误

调用方识别方式

1. 先看 HTTP 状态码。
2. 如果 body 中存在 error.type，说明错误由网关生成。
3. 如果 body 中是业务错误结构，说明该错误为原样返回。
4. 排障时优先记录 error.request_id 或响应中的 trace 信息。