用户错误码指南
本文档面向平台使用者，汇总了调用 AI 模型接口时可能遇到的内部错误码及其解决方案。
响应格式：错误响应遵循 OpenAI 格式：
{"error": {"message": "...", "type": "neolink_error", "code": "..."}}。如何定位：可通过 HTTP 状态码快速定位错误分类，再结合响应体中的
code或message字段匹配具体错误。
目录
- HTTP 400 — 请求错误
- HTTP 401 — 认证失败
- HTTP 402 — 额度/余额不足
- HTTP 403 — 权限/实体/缓存拒绝
- HTTP 404 — 未找到
- HTTP 413 — 请求体过大
- HTTP 429 — 频率限制
- HTTP 500 — 服务器内部错误
- HTTP 501 — 未实现
- HTTP 503 — 服务不可用
HTTP 400 — 请求错误
请求参数不正确或请求格式有问题，需修改请求后重试。
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
invalid_request | Invalid request, <具体错误详情> | 请求参数未通过校验，例如缺少必填字段、字段类型错误、取值范围不符等 | 检查请求体是否符合对应接口的参数规范，按 message 中的具体提示修正后重试 |
invalid_request | invalid request type, expected dto.GeneralOpenAIRequest, got %T | 平台内部请求类型转换失败，通常由请求体结构不匹配导致 | 核对请求体是否为标准 OpenAI Chat Completions 格式，调整后重试 |
invalid_request | invalid request type, expected dto.ImageRequest, got %T | 图像生成接口的请求体类型不匹配 | 确认请求体符合图像生成接口（如 DALL·E）的参数规范 |
invalid_request | invalid request type, expected dto.RerankRequest, got %T | Rerank 接口的请求体类型不匹配 | 确认请求体符合 Rerank 接口的参数规范 |
invalid_request | invalid request type, expected *dto.GeminiChatRequest, got %T | Gemini 接口的请求体类型不匹配 | 确认请求体符合 Gemini Chat 接口的参数规范 |
invalid_request | invalid request type, expected *dto.EmbeddingRequest, got %T | Embedding 接口的请求体类型不匹配 | 确认请求体符合 Embedding 接口的参数规范 |
invalid_request | invalid request type, expected *dto.ClaudeRequest, got %T | Claude 接口的请求体类型不匹配 | 确认请求体符合 Claude 接口的参数规范 |
invalid_request | unsupported endpoint %q for api type %d | 请求的 endpoint 路径与当前 API 类型不匹配 | 检查请求路径是否正确，确认该模型/渠道支持的接口端点 |
invalid_request | invalid request type, expected dto.OpenAIResponsesRequest or dto.OpenAIResponsesCompactionRequest, got %T | Responses 接口的请求体类型不匹配 | 确认请求体符合 OpenAI Responses 接口的参数规范 |
chat_to_responses_unsupported_parameter | this request cannot be bridged from chat completions to responses because it uses unsupported parameter: <params> | Chat→Responses 桥接时，请求使用了 Responses API 无法表达的参数（如 stop），且规则配置为 reject | 修改请求参数，移除不兼容的参数后重试；或联系管理员调整桥接规则为 fallback 模式 |
sensitive_words_detected | sensitive words detected | 输入内容命中平台敏感词过滤规则 | 修改输入内容，移除敏感词后重试 |
read_request_body_failed | http: request body too large、unexpected EOF、读取请求体失败: <底层IO错误> 等 | 平台读取请求体时发生 IO 错误（如请求体过大、连接中断等） | 检查网络连接是否稳定；确认请求体已完整发送后重试 |
model_price_error | 模型 gpt-4 的价格未配置。请前往「系统设置 → 运营设置」开启自用模式，或在「系统设置 → 分组与模型定价设置」中为该模型配置价格 等 | 平台查询该模型定价时出错（如定价未配置、数据库查询失败等） | 稍后重试；如持续出现，请联系管理员检查模型定价配置 |
channel:param_override_invalid | 渠道参数覆盖配置无效: invalid character 'x' looking for beginning of value 等 | 渠道侧的参数覆盖配置 JSON 格式错误 | 联系管理员检查渠道的"参数覆盖"配置是否为合法 JSON |
| — | Invalid request, <具体错误> | 分发器解析请求时出错 | 按 message 中的具体提示修正请求参数后重试 |
| — | 无效的渠道 Id | 请求中指定的渠道 ID 无效或不存在 | 检查请求中是否指定了正确的渠道 ID；普通用户不支持指定渠道 |
| — | 未指定模型名称，模型名称不能为空 | 请求未携带模型名称 | 在请求体的 model 字段中填写模型名称后重试 |
| — | 无效的playground请求, <错误> | Playground 请求格式不正确 | 按 message 中的提示调整 Playground 请求结构 |
| — | Action query parameter is required | 即梦（Jimeng）适配接口缺少 Action 查询参数 | 在请求 URL 中补充 Action 查询参数 |
| — | Invalid request body | 即梦（Jimeng）适配接口的请求体格式错误 | 检查请求体是否为合法 JSON 且符合接口规范 |
| — | task_id is required for CVSync2AsyncGetResult | 同步转异步获取结果时未提供 task_id | 在请求中携带有效的 task_id 参数后重试 |
HTTP 401 — 认证失败
令牌（API Key）认证失败，需检查令牌有效性。
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
| — | 无效的令牌 | 请求使用的令牌在平台中不存在或已被删除 | 核对 API Key 是否正确；如不确定，联系管理员重新获取令牌 |
| — | 该令牌已过期 | 令牌已超过有效期 | 联系管理员续期或申请新的令牌 |
| — | 该令牌已被删除 | 令牌已被管理员删除 | 联系管理员确认令牌状态，必要时申请新令牌 |
| — | 该令牌状态不可用 | 令牌状态异常（非启用、非过期、非耗尽） | 联系管理员确认令牌状态 |
| — | 未提供令牌 | 请求未携带 API Key | 在请求头中添加 Authorization: Bearer sk-xxxx 后重试 |
| — | 无效的令牌，数据库查询出错，请联系管理员 | 令牌查询时数据库异常 | 稍后重试；如持续出现请联系管理员 |
| — | 该成员已被禁用，无法调用 API | 令牌所属的企业成员已被禁用 | 联系管理员启用该成员 |
| — | 该企业已被禁用，API Key 不可调用 | 令牌所属企业已被禁用 | 联系管理员启用企业 |
HTTP 402 — 额度/余额不足
令牌、成员、部门或企业的额度/余额不足以完成本次请求。以下错误码来自预扣费额度校验环节，details 字段会附带剩余额度、请求额度等明细。
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
TOKEN_QUOTA_INSUFFICIENT | 令牌总额度不足 | 令牌剩余总额度小于本次请求预扣费额度 | 联系管理员为令牌充值总额度 |
TOKEN_DAILY_QUOTA_ZERO | 令牌日额度为0，禁止调用 | 令牌的日额度被配置为 0 | 联系管理员调高令牌日额度 |
TOKEN_DAILY_QUOTA_EXHAUSTED | 令牌日额度已用尽 | 令牌今日已用量达到日额度上限 | 次日 0 点自动重置；或联系管理员调高日额度 |
TOKEN_MONTHLY_QUOTA_ZERO | 令牌月额度为0，禁止调用 | 令牌的月额度被配置为 0 | 联系管理员调高令牌月额度 |
TOKEN_MONTHLY_QUOTA_EXHAUSTED | 令牌月额度已用尽 | 令牌本月已用量达到月额度上限 | 次月 1 日自动重置；或联系管理员调高月额度 |
MEMBER_DAILY_QUOTA_ZERO | 成员日额度为0，禁止调用 | 成员的日额度被配置为 0 | 联系管理员调高成员日额度 |
MEMBER_DAILY_QUOTA_EXHAUSTED | 成员日额度已用尽 | 成员今日已用量达到日额度上限 | 次日 0 点自动重置；或联系管理员调高日额度 |
MEMBER_MONTHLY_QUOTA_ZERO | 成员月额度为0，禁止调用 | 成员的月额度被配置为 0 | 联系管理员调高成员月额度 |
MEMBER_MONTHLY_QUOTA_EXHAUSTED | 成员月额度已用尽 | 成员本月已用量达到月额度上限 | 次月 1 日自动重置；或联系管理员调高月额度 |
ORG_MONTHLY_QUOTA_ZERO | 部门月度预算为0，禁止调用 | 部门的月度预算被配置为 0 | 联系管理员调整部门月度预算 |
ORG_MONTHLY_QUOTA_EXHAUSTED | 部门月度预算已用尽 | 部门本月已用量达到月度预算上限 | 次月 1 日自动重置；或联系管理员调高月度预算 |
ENTERPRISE_BALANCE_INSUFFICIENT | 企业余额不足 | 企业账户余额小于本次请求预扣费额度 | 联系管理员为企业账户充值 |
USER_BALANCE_INSUFFICIENT | 用户余额不足 | 用户账户余额小于本次请求预扣费额度 | 联系管理员为用户账户充值 |
HTTP 403 — 权限/实体/缓存拒绝
请求被拒绝，原因可能是权限不足、实体无效、缓存异常、IP 限制等。
1. 认证阶段额度耗尽
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
| — | 该令牌额度已用尽 TokenStatusExhausted[sk-xxx***xxx] | 令牌状态为已耗尽（认证阶段检测） | 联系管理员为令牌充值额度 |
| — | [sk-xxx***xxx] 该令牌额度已用尽 ... | 令牌剩余额度 ≤ 0（运行时校验） | 联系管理员为令牌充值额度 |
2. 实体查找/参数类
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
TOKEN_INVALID | 令牌无效 | 预扣费时令牌实体无效 | 联系管理员确认令牌配置是否正常 |
MEMBER_INVALID | 成员无效 | 令牌所属成员已被禁用或不存在 | 联系管理员确认成员状态 |
ORG_INVALID | 部门无效 | 令牌所属部门已被禁用或不存在 | 联系管理员确认部门状态 |
ENTERPRISE_INVALID | 企业无效 | 令牌所属企业已被禁用或不存在 | 联系管理员确认企业状态 |
USER_INVALID | 用户无效 | 令牌所属用户已被禁用或不存在 | 联系管理员确认用户状态 |
ENTITY_NOT_FOUND | 实体未找到（Lua 兜底消息）；构造函数可生成 token未找到、user未找到、member未找到、organization未找到、enterprise未找到 | 预扣费时未找到对应的实体（令牌/成员/部门/企业等） | 联系管理员确认相关实体配置是否正常 |
INVALID_PARAMETERS | 无效参数（Lua 兜底消息） | 预扣费参数校验未通过 | 按 message 中的提示修正参数；如需调整配置请联系管理员 |
insufficient_quota | 预扣费额度失败, [ERROR_CODE] message，例如 预扣费额度失败, [TOKEN_QUOTA_INSUFFICIENT] 令牌总额度不足 | 预扣费校验失败，且未匹配到上述具体错误码（通用兜底） | 联系管理员排查额度配置，确认令牌/成员/部门/企业的额度或余额是否充足 |
3. 缓存/脚本类
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
CACHE_UPDATE_FAILED | 缓存更新失败 | 预扣费时更新 Redis 缓存失败 | 稍后重试；如持续出现请联系管理员检查缓存服务 |
LUA_SCRIPT_EXECUTION_FAILED | Lua脚本执行失败: pre_consume_personal 或 Lua脚本执行失败: pre_consume_enterprise | 预扣费执行的 Lua 脚本异常 | 稍后重试；如持续出现请联系管理员检查脚本配置 |
4. 权限访问类
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
access_denied | 资源访问被拒绝 | 令牌无权访问所请求的模型资源 | 联系管理员为令牌开通对应模型的访问权限 |
| — | 该令牌无权访问任何模型 | 令牌未绑定任何可用模型 | 联系管理员为令牌分配模型权限 |
| — | 该令牌无权访问模型 <modelCode> | 令牌无权访问指定的模型 | 联系管理员为令牌开通该模型的访问权限 |
| — | 该渠道已被禁用 | 请求指定的渠道已被管理员禁用 | 联系管理员确认渠道状态；或不在请求中指定渠道 |
| — | 无权访问该分组 | 令牌无权访问请求所用的分组 | 联系管理员为令牌开通该分组的访问权限 |
| — | 无法解析客户端 IP 地址 | 平台无法解析请求方的 IP 地址 | 检查网络环境；如通过代理访问，请确认代理头配置正确 |
| — | 您的 IP 不在令牌允许访问的列表中 | 令牌配置了 IP 白名单，当前请求 IP 不在列表中 | 联系管理员将当前 IP 加入令牌的 IP 白名单 |
| — | 用户已被封禁 | 令牌所属用户已被管理员封禁 | 联系管理员解封用户账号 |
| — | 普通用户不支持指定渠道 | 普通用户无权在请求中指定渠道 | 移除请求中的渠道指定参数；或联系管理员提升用户权限 |
| — | 令牌无可用的有效分组 | 令牌绑定的所有分组均已被删除或未配置倍率 | 联系管理员为令牌绑定有效的分组 |
| — | user group is empty | 令牌分组策略中用户分组为空 | 联系管理员为用户配置有效分组 |
| — | invalid subject type: <type> | 分组策略中主体类型不合法 | 联系管理员检查分组策略的主体类型配置 |
| — | 该模型为国内模型，您的账户仅允许访问国际模型 | 令牌账户仅允许访问国际模型，但请求的模型为国内模型 | 更换为国际模型；或联系管理员调整账户的模型访问范围 |
| — | 该模型为国际模型，您的账户仅允许访问国内模型 | 令牌账户仅允许访问国内模型，但请求的模型为国际模型 | 更换为国内模型；或联系管理员调整账户的模型访问范围 |
HTTP 404 — 未找到
请求的接口路径不存在，或指定模型在当前分组下无可用渠道。
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
| — | Invalid URL (<Method> <Path>) | 请求的 URL 路径不在平台支持的接口列表中 | 检查请求的 URL 路径和 HTTP 方法是否正确，参考接口文档调整 |
model_not_found | 分组 <group> 下模型 <model> 无可用渠道（distributor） | 指定分组下没有为该模型配置可用渠道 | 联系管理员为该分组添加支持该模型的渠道，或更换为已配置的模型 |
model_not_found | 获取分组 <group> 下模型 <model> 的可用渠道失败（distributor）: <错误> | 平台查询可用渠道时出错 | 稍后重试；如持续出现请联系管理员检查分组与渠道配置 |
model_not_found | 令牌的所有分组（<groups>）均不支持模型 <model> | 令牌绑定的所有分组均未配置该模型 | 联系管理员在某个分组下添加该模型，或为令牌绑定支持该模型的分组 |
model_not_found | user group is empty | 多分组动态选组时用户分组为空 | 联系管理员为用户配置有效分组 |
HTTP 413 — 请求体过大
请求体超过了平台允许的最大长度。
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
read_request_body_failed | http: request body too large 或类似 IO 错误 | 请求体大小超过平台限制 | 减小请求体体积，例如缩短输入文本、减少图片数量、降低附件大小后重试 |
HTTP 429 — 频率限制
请求频率超过限制，需降低请求速率。
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
rate_limit_exceeded | 您已达到请求数限制：<X>分钟内最多请求<Y>次 | 单位时间内成功请求数超过令牌配置的 RPM 限制（V1） | 降低请求频率，等待限制窗口（X 分钟）结束后重试 |
rate_limit_exceeded | 您已达到总请求数限制：<X>分钟内最多请求<Y>次，包括失败次数，请检查您的请求是否正确 | 单位时间内总请求数（含失败请求）超过限制（V1） | 降低请求频率；同时检查请求参数是否正确以减少失败请求，避免占用配额 |
rate_limit_exceeded | enterprise RPM limit exceeded (model: <model>, limit: <N>/<M>min) | 企业级模型 RPM 限流触发（V2） | 降低请求频率，等待限制窗口结束后重试 |
rate_limit_exceeded | enterprise TPM limit exceeded (model: <model>, limit: <N>/<M>min) | 企业级模型 TPM 限流触发（V2） | 降低请求频率或减少单次请求 Token 数，等待限制窗口结束后重试 |
rate_limit_exceeded | user RPM limit exceeded (model: <model>, limit: <N>/<M>min) | 用户级模型 RPM 限流触发（V2） | 降低请求频率，等待限制窗口结束后重试 |
rate_limit_exceeded | user TPM limit exceeded (model: <model>, limit: <N>/<M>min) | 用户级模型 TPM 限流触发（V2） | 降低请求频率或减少单次请求 Token 数，等待限制窗口结束后重试 |
HTTP 500 — 服务器内部错误
平台内部处理请求时发生错误，多数情况可重试解决。
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
count_token_failed | Token 计数失败: <底层错误>，例如 Token 计数失败: failed to count tokens | 平台计算请求 Token 数时发生内部错误 | 稍后重试；如持续出现请联系管理员 |
gen_relay_info_failed | 生成 Relay 信息失败: <底层错误>，例如 生成 Relay 信息失败: channel not found | 平台生成转发元信息时出错 | 稍后重试；如持续出现请联系管理员 |
get_channel_failed | 获取渠道失败: <底层错误>，例如 获取渠道失败: channel is nil | 平台获取可用渠道时出错 | 稍后重试；如持续出现请联系管理员检查渠道配置 |
do_request_failed | 执行请求失败: <底层错误>，例如 执行请求失败: dial tcp: connection refused | 平台向下游发起请求时发生网络或连接错误 | 稍后重试；如持续出现请联系管理员 |
invalid_api_type | 无效的 API 类型 | 渠道配置的 API 类型不合法 | 联系管理员检查渠道的 API 类型配置 |
json_marshal_failed | JSON 序列化失败: <底层错误>，例如 JSON 序列化失败: json: unsupported type: chan int | 平台序列化请求体时出错 | 稍后重试；如持续出现请联系管理员 |
convert_request_failed | 请求转换失败: <底层错误>，例如 请求转换失败: unsupported model format | 平台将请求转换为上游格式时出错 | 稍后重试；如持续出现请联系管理员 |
bad_request_body | 请求体格式错误: <底层错误>，例如 请求体格式错误: invalid character 'x' looking for beginning of value | 平台解析特定渠道（如火山 TTS、AWS）的请求体时出错 | 检查请求体是否符合该渠道的参数规范后重试 |
query_data_error | 数据查询错误: <底层错误>，例如 数据查询错误: record not found | 预扣费环节查询数据时出错 | 稍后重试；如持续出现请联系管理员 |
update_data_error | 数据更新错误: <底层错误>，例如 数据更新错误: Error 1062: Duplicate entry | 平台更新数据时出错 | 稍后重试；如持续出现请联系管理员 |
channel:no_available_key | 渠道没有可用的密钥 | 渠道下所有密钥均不可用（被禁用或轮空） | 联系管理员检查渠道密钥配置，确认密钥有效且未全部禁用 |
channel:header_override_invalid | 渠道请求头覆盖配置无效: invalid character 'x' looking for beginning of value 等 | 渠道的请求头覆盖配置 JSON 格式错误 | 联系管理员检查渠道的"请求头覆盖"配置是否为合法 JSON |
channel:model_mapped_error | 模型映射错误: <底层错误>，例如 模型映射错误: target model not found in mapping | 渠道模型映射配置有误 | 联系管理员检查渠道的模型映射配置 |
channel:aws_client_error | AWS 客户端错误 | AWS 渠道客户端初始化或调用失败 | 联系管理员检查 AWS 渠道配置（密钥、区域等） |
channel:invalid_key | 渠道密钥无效 | 渠道配置的密钥无效 | 联系管理员检查渠道密钥是否正确且有效 |
aws_invoke_error | AWS 调用错误 | 调用 AWS 服务时出错 | 稍后重试；如持续出现请联系管理员检查 AWS 渠道配置 |
prompt_blocked | 输入被阻止 | 输入内容被上游安全策略阻止 | 修改输入内容后重试；如确认内容合规但持续被阻止，请联系管理员 |
empty_response | 空响应 | 上游返回了空响应 | 稍后重试；如持续出现请联系管理员 |
| — | rate_limit_check_failed | 频率限制检查环节发生内部错误 | 稍后重试；如持续出现请联系管理员 |
| — | 企业信息错误 | 令牌所属企业信息异常 | 联系管理员确认企业配置是否正常 |
| — | record not found、user cache incomplete: missing Setting field 等 | 获取用户缓存时出错（如用户已被软删除、缓存数据不完整等） | 稍后重试；如持续出现请联系管理员 |
HTTP 501 — 未实现
请求的接口尚未实现。
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
api_not_implemented | API not implemented | 请求的接口路径存在但尚未实现 | 确认接口路径是否正确；该接口可能尚未上线，请联系管理员确认 |
HTTP 503 — 服务不可用
当前无可用渠道处理请求，通常为渠道配置或容量问题。
| code | message | 原因说明 | 解决方案 |
|---|---|---|---|
| — | 无可用的 Kling 通道 | 当前分组下没有可用的 Kling 渠道 | 联系管理员为分组添加可用的 Kling 渠道 |
| — | 无可用的 Kling 通道（渠道 <name> 未启用或不存在） | Kling 固定渠道未启用或不存在 | 联系管理员检查渠道配置 |
| — | 无可用的 MiniMax 通道 | 当前分组下没有可用的 MiniMax 渠道 | 联系管理员为分组添加可用的 MiniMax 渠道 |
| — | 无可用的 MiniMax 通道（渠道 <name> 未启用或不存在） | MiniMax 固定渠道未启用或不存在 | 联系管理员检查渠道配置 |
| — | channel is nil 或 no keys available | 平台初始化指定渠道上下文时出错（渠道为空或密钥不可用） | 联系管理员检查渠道配置是否正确 |
附：错误响应示例
json
{
"error": {
"code": "model_not_found",
"message": "分组 default 下模型 happyhorse-1.0-i2v-720p 无可用渠道（distributor） (request id: 20260630102222308068043y9Cfyxgr)",
"type": "neolink_error"
}
}json
{
"error": {
"code": "TOKEN_MONTHLY_QUOTA_EXHAUSTED",
"message": "令牌月额度已用尽",
"type": "neolink_error"
}
}json
{
"error": {
"code": "invalid_request",
"message": "Invalid request, <具体错误> (request id: <id>)",
"type": "neolink_error"
}
}json
{
"error": {
"code": "rate_limit_exceeded",
"message": "enterprise RPM limit exceeded (model: gpt-4, limit: 100/1min) (request id: <id>)",
"type": "neolink_error"
}
}