GenStudio LLM API 错误码

本页适用于 GenStudio 的 LLM、向量嵌入和重排序等兼容接口。如果错误发生在响应开始前，通常使用 HTTP 状态码表达处理结果；响应体格式取决于所调用的兼容协议和端点。流式响应开始后发生的错误可能保留 HTTP 200，或表现为响应流中断。

判断错误响应格式

部分 OpenAI 兼容端点返回 OpenAI 错误对象。此时，error.code 是字符串，不会直接返回本文列出的平台数字错误码：

{
  "error": {
    "message": "请使用正确的api key进行请求",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Anthropic Messages 兼容端点的错误响应可能使用数字 code 和 msg：

{
  "code": 10009,
  "msg": "请使用正确的api key进行请求"
}

同一端点也可能返回 Claude 错误对象：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid request"
  }
}

重排序等其他兼容端点还可能返回纯文本或端点自有的 JSON 错误。

错误响应还可能使用所选模型定义的字段格式。此时，请以实际 HTTP 状态码和完整响应体为准，字段名称、错误码及其数据类型可能不在本页的固定列表中。部分 OpenAI 兼容端点会将 429 错误统一表示为 rate_limit_exceeded。

排查错误时，先根据实际响应确定字段格式：

• OpenAI 错误对象：检查 HTTP 状态码以及 error.code、error.type 和 error.message。
• Claude 错误对象：检查 HTTP 状态码以及 error.type 和 error.message。
• 平台数字错误对象：检查 HTTP 状态码以及数字 code 和 msg。
• 其他端点错误：检查 HTTP 状态码和完整的纯文本或 JSON 响应。
• 其他响应格式：保留完整响应体；不要假设其字段格式与上述对象相同。
• 本文档中用 {...} 表示运行时详情；实际响应会替换为具体字段、模型、限制值或失败原因。

同一项平台错误在不同响应格式中可能使用不同的对外错误码。不要假设本文列出的数字错误码一定会直接出现在所有兼容端点的响应体中。

400 Bad Request

请求格式、参数、模型 ID 或模型协议不符合要求。

invalid_request

• HTTP 状态码：400。
• OpenAI error.code：invalid_request。
• 错误信息示例：Invalid request。部分请求还可能返回 Invalid JSON in request body 或 Failed to read request body。
• 可能原因：请求体不是有效 JSON、请求缺少必填信息，或请求信息无效。
• 处理建议：检查 JSON 格式和必填字段；如果请求本身无误但问题持续出现，请记录请求信息并联系技术支持。
• 是否建议重试：否。修正请求后再重新提交。

image_fetch_failed

• HTTP 状态码：400。
• OpenAI error.code：image_fetch_failed。
• 错误信息：Failed to fetch image from upstream URL
• 适用场景：多模态 LLM 对话请求需要读取图片 URL。此错误不适用于图片生成接口。
• 可能原因：图片 URL 无法访问、下载失败或响应内容读取失败。
• 处理建议：确认图片 URL 有效、未过期、可正常访问，并返回受支持的图片内容。
• 是否建议重试：视情况。先检查图片 URL、访问权限、有效期和内容；如果确认是暂时的网络或读取失败，可稍后重试。

10001

• 错误信息格式：Invalid Field {field}
• 可能原因：请求字段缺失、格式错误或取值不合法。
• 处理建议：按接口说明检查请求参数名称、类型和取值范围。
• 是否建议重试：否。

10007

• 错误信息格式：Bad Request: {reason}
• 可能原因：请求体、消息类型或其他请求条件不满足要求。
• 处理建议：根据返回的具体错误信息修改请求。
• 是否建议重试：否。

40301

• 错误信息格式：The model {model} does not exist or you do not have access to it.
• 可能原因：模型 ID 不存在、模型不可见，或当前兼容协议不支持该模型。
• 处理建议：确认模型 ID、API 路径和兼容协议匹配；Anthropic 兼容接口仅支持适配该协议的模型。
• 是否建议重试：否。

70000

• 错误信息格式：Exceeding the limiting length: {limit}
• 可能原因：生成长度或输入内容超出模型限制。
• 处理建议：减少输入长度，或调低 max_tokens / max_completion_tokens。
• 是否建议重试：否。

10010 / model_not_ready

• HTTP 状态码：400。
• OpenAI error.code：model_not_ready。对应的平台数字错误码为 10010。
• 错误信息："推理服务不在运行中，请检查后再重试"
• 适用场景：通过模型服务部署 ID 调用 Chat Completions 接口。
• 可能原因：专属模型服务暂不可用或尚未进入运行状态。
• 处理建议：检查模型服务状态；等待服务进入运行状态后重试。如持续出现，请联系技术支持。
• 是否建议重试：是。

401 Unauthorized

身份验证失败或 API Key 不可用。

10003

• 错误信息："Not login"
• 可能原因：未登录，或请求未携带有效登录态。
• 处理建议：API 调用应使用有效 API Key；控制台请求请重新登录。
• 是否建议重试：否。

10009

• 错误信息："请使用正确的api key进行请求"
• 可能原因：Authorization 请求头格式错误、API Key 无效或已失效。
• 处理建议：使用 Authorization: Bearer ＜API Key＞，并确认 API Key 未删除、未过期。
• 是否建议重试：否。

10018

• 错误信息："APIKEY 已被用户禁用， 请检查后再试"
• 可能原因：API Key 已被禁用。
• 处理建议：在控制台启用 API Key，或更换可用 API Key。
• 是否建议重试：否。

402 Payment Required

账户余额、预算或套餐状态不满足调用条件。

10017

• 错误信息："CashAccount: not enough balance"
• 可能原因：账户余额不足。
• 处理建议：补足账户余额。余额恢复后，服务可能需要等待约 5 分钟自动恢复。
• 是否建议重试：否。

10024

• 错误信息："当前账号消费已超过预算金额上限"
• 可能原因：账号消费达到预算上限。
• 处理建议：调整预算上限，或联系管理员处理预算限制。
• 是否建议重试：否。

403 Forbidden

当前租户或账号没有访问指定模型或 API 路径的权限。

10008

• 错误信息："暂无该模型访问权限，请到官网进行申请"
• 可能原因：当前租户没有访问该模型的权限。
• 处理建议：确认模型是否已开通；如需使用该模型，请申请模型访问权限。
• 是否建议重试：否。

10025

• HTTP 状态码：403。
• 错误信息：以实际响应为准，常见返回为 功能暂不可用。
• 可能原因：当前账号暂时无法使用该 API。
• 处理建议：确认服务开通状态和账号权限；如需继续使用，请联系管理员或技术支持。
• 是否建议重试：否。

404 Not Found

请求路径、资源或端点不存在。请检查 Base URL、端点路径、模型 ID 和资源 ID；详细排查方法参见本页的“LLM API 返回 404 错误”。

413 Request Entity Too Large

请求体超过大小限制。

10019

• 错误信息："Request body too large"
• 可能原因：请求体过大。
• 处理建议：减少消息数量、上下文长度、图片或音频等输入内容。
• 是否建议重试：否。

429 Too Many Requests

请求频率、Token 速率、并发或周期配额超过限制。

根据端点的响应格式，此类错误可能返回字符串 error.code=rate_limit_exceeded 或数字错误码。

20013 / rate_limit_exceeded

• HTTP 状态码：429。
• 错误码：OpenAI 错误对象使用 rate_limit_exceeded；平台数字错误对象使用 20013。
• 错误信息：以实际响应为准。
• 常见返回：RPM exceeded at apikey level、RPD exceeded at apikey level、TPM exceeded at apikey level、RPM exceeded at tenant level、RPD exceeded at tenant level、TPM exceeded at tenant level、Concurrency exceeded.、Service concurrency exceeded.、Service quota exceeded.
• 可能原因：单个 API Key、账号、请求规则或所选服务触发请求次数、Token 速率、并发或配额限制。
• 处理建议：降低请求频率和并发，减少输入长度或生成 Token 数；如果是服务侧并发能力不足，可购买包并发服务；如果是服务或资源配额限制，请稍后重试或联系技术支持。
• 是否建议重试：是。

499 Client Closed Request

客户端或中间代理在请求完成前断开连接。

client_closed_request

• HTTP 状态码：499。
• OpenAI error.code：client_closed_request。
• 错误信息：Client Closed Request 或 Client closed request。
• 可能原因：调用方主动取消请求、请求被取消，或连接中断。
• 处理建议：检查客户端取消逻辑和网络连接；确认仍需要结果后再重新提交。连接已经断开时，调用方可能只能观察到响应中断，而无法收到完整的 499 JSON 响应。
• 是否建议重试：视情况。

5xx 服务端错误

平台或模型调用发生异常。部分错误可能使用所选模型定义的响应格式，而不使用本节列出的固定 error.code。

20004

• HTTP 状态码：500。
• 错误信息格式：Json marshal fail {reason}
• 可能原因：平台生成响应时发生异常。
• 处理建议：稍后重试；如持续出现，请记录请求 ID 并联系技术支持。
• 是否建议重试：是。

20023

• HTTP 状态码：500。
• OpenAI error.code：gateway_internal_error。
• 错误信息："系统繁忙，请稍后再试"
• 可能原因：平台暂时繁忙或发生未知错误。
• 处理建议：稍后重试；如持续出现，请联系技术支持。
• 是否建议重试：是。

gateway_internal_error

• HTTP 状态码：500。
• OpenAI error.code：gateway_internal_error。
• 错误信息：Internal Server Error
• 可能原因：平台遇到未能进一步分类的错误。此错误不一定对应数字错误码 20023。
• 处理建议：稍后重试；如持续出现，请记录请求信息并联系技术支持。
• 是否建议重试：是。

router_internal_error

• HTTP 状态码：500。
• OpenAI error.code：router_internal_error。
• 错误信息格式：请求处理失败的具体说明。
• 可能原因：平台处理请求或多模态输入时发生未知错误。
• 处理建议：稍后重试；如持续出现，请记录请求信息并联系技术支持。
• 是否建议重试：是。

upstream_connection_error

• HTTP 状态码：502。
• OpenAI error.code：upstream_connection_error。
• 错误信息格式：模型连接失败或响应不完整、无效的具体说明。
• 可能原因：模型连接异常，或未收到完整、有效的模型响应。
• 处理建议：稍后重试；如持续出现，请记录请求信息并联系技术支持。
• 是否建议重试：是。

20002

• HTTP 状态码：503。
• 错误信息格式：Set session error {reason}
• 可能原因：登录态或会话信息处理失败。
• 处理建议：重新登录后重试；API 调用请确认使用 API Key。
• 是否建议重试：是。

service_unavailable

• HTTP 状态码：503。
• OpenAI error.code：service_unavailable。
• 错误信息格式：服务暂不可用的具体说明。
• 可能原因：所选模型暂无可用资源，或服务暂时不可用。
• 处理建议：稍后重试；如持续出现，请联系技术支持。
• 是否建议重试：是。

已弃用错误码

以下错误码已弃用，不应作为新集成的处理依据；现有集成如仍需兼容历史响应，可保留相应处理。遇到相近错误时，请以实际 HTTP 状态码、响应体格式和错误信息为准，不要将其他错误码视为直接替代。

10006（已弃用）

• 状态：已弃用。
• 替代错误码：暂无已确认的一一对应替代错误码。
• 错误信息：Route Not Found
• 可能原因：API 路径不存在，或 Base URL 与端点路径拼接错误。
• 处理建议：检查 Base URL、/v1、/chat/completions、/messages 等路径片段是否重复或缺失。
• 是否建议重试：否。

20022（已弃用）

• 状态：已弃用。
• 替代错误码：暂无已确认的一一对应替代错误码。
• 错误信息格式：Connection Failed: {reason}
• 可能原因：请求未能完成。
• 处理建议：稍后重试；如持续出现，请记录完整响应并联系技术支持。
• 是否建议重试：是。

20404（已弃用）

• 状态：已弃用。
• 替代错误码：暂无已确认的一一对应替代错误码。
• 错误信息格式：Not found error: {reason}
• 可能原因：请求的资源不存在。
• 处理建议：确认资源 ID、模型服务部署 ID 或其他路径参数是否正确。
• 是否建议重试：否。

40302（已弃用）

• 状态：已弃用。
• 替代错误码：暂无已确认的一一对应替代错误码。
• 错误信息格式：Param {param} Invalid
• 可能原因：聊天请求参数无效。
• 处理建议：根据返回的参数名修改请求参数。
• 是否建议重试：否。

错误处理和端点路径排查

错误处理建议

1. 先判断响应形态：先看 HTTP 状态码，再确认响应体使用 OpenAI、Claude、平台数字错误对象，还是其他格式。
2. 判断是否可重试：400、401、402、403、404 和 413 通常需要先修正请求、权限、余额或配置；model_not_ready 是例外，应在模型服务进入运行状态后重试。429、502、503 和其他 5xx 可按退避策略重试。遇到 499 时，先排查调用方取消或连接中断。
3. 保留排查信息：记录 HTTP 状态码、完整响应体、实际错误码和错误信息、响应体 id、响应头 traceresponse、模型 ID、请求时间和耗时。
4. 避免立即重放大请求：遇到 429、413 或 70000 时，先降低并发、缩短上下文或减少生成长度。
5. 识别其他错误格式：如果响应字段或错误码不在本页列表中，请按实际错误信息排查，并保留完整响应供技术支持分析。

LLM API 返回 404 错误

404 错误一般是因为 API 域名路径配置错误。由于第三方工具在处理 API URL 时存在一定差异，请尤其注意以下几点：

• 工具是否自行拼接 /v1/chat/completions、/v1/embeddings、/v1/messages 等片段，无需用户填写。
• 工具是否自行拼接 /v1 片段，无需用户填写。
• 工具是否要求用户填写完整的 API 请求地址。
• 如果 URL 组合无误，再检查模型 ID 是否可见，以及当前模型是否支持所选兼容协议。