> ## Documentation Index > Fetch the complete documentation index at: https://docs.flexinference.com/llms.txt > Use this file to discover all available pages before exploring further. # 错误 > 各接口的错误封装、FlexInference 代码以及提供商错误如何标准化。 错误使用您调用的端点的封装。`/v1/responses` 和 `/v1/chat/completions` 返回 OpenAI 格式的错误。`/v1/messages` 返回 Anthropic 格式的错误。`/v1/interactions` 返回 Google 格式的错误。FlexInference 错误和上游提供商错误遵循相同的规则，因此每个端点都有一种错误格式。 遇到 5xx 错误或超时？请首先查看 [status.flexinference.com](https://status.flexinference.com)。它显示了 API、网站、文档和 MCP 服务器的实时运行状态，以及任何正在处理的事件。 在 `/v1/responses` 和 `/v1/chat/completions` 上，错误使用 OpenAI 封装： ```json theme={null} { "error": { "message": "The API key on this request was rejected - either it does not match FlexInference's key format (`flex_live_` followed by 24 hex characters and a 6-hex checksum), or it is well-formed but does not match any key on record. Copy the exact, current key from the FlexInference dashboard under Settings -> API keys, then send it as `Authorization: Bearer `.", "type": "authentication_error", "code": "invalid_api_key", "param": null, "doc_url": "https://docs.flexinference.com/errors#invalid_api_key" } } ``` `/v1/messages` 上的相同错误使用 Anthropic 格式。在 `/v1/interactions` 上，它使用 Google 格式： ```json theme={null} { "type": "error", "error": { "type": "authentication_error", "message": "..." } } ``` ```json theme={null} { "error": { "code": 401, "message": "...", "status": "UNAUTHENTICATED" } } ``` HTTP 状态和消息在不同接口上保持不变；只有封装方式会改变。OpenAI 封装包含完整的详细信息。`type` 使用 OpenAI 类别（`invalid_request_error`、`authentication_error`、`rate_limit_error`），以及用于内部故障的 `flexinference_error` 和当计费状态暂停可计费请求时的 `billing_error`。`code` 是机器可读的原因。当适用时，`param` 会指出有问题的字段。`doc_url` 链接到下方该代码的行，如果未知则为 `null`。Anthropic 格式包含从状态映射的 Anthropic `type` 和消息。Google 格式包含数字 `code`、消息和规范的 `status`。FlexInference 特定的 `code` 和 `doc_url` 仅出现在 OpenAI 封装中。 ## FlexInference 代码 这些代码来自 FlexInference。根据 `error.code` 进行分支判断；`error.message` 是为开发者编写的，并在存在修复方案时包含修复说明。 有几个错误涉及 `start_within`。对于支持 flex 的模型上的持续时间值，FlexInference 会首先尝试更便宜的 flex 层级。如果 flex 无法在该窗口内启动，FlexInference 会将相同的请求发送到标准层级。标准层级是备用路径，而不是首次尝试。 | 状态 | 代码 | 含义 | | ----- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` | `missing_api_key` | 缺少 `Authorization` 头部，或者其值不是 `Bearer `。请发送 `Authorization: Bearer `。 | | `401` | `invalid_api_key` | 密钥不符合 FlexInference 的格式（`flex_live_` + 24 个十六进制字符 + 6 个十六进制校验和），或者格式匹配但未知，因为它已被撤销、重新生成或输入错误。请从控制面板复制当前密钥。 | | `429` | `rate_limit_exceeded` | 请求达到了以下限制之一：来自您的客户端 IP 的认证失败尝试次数、来自单个密钥或客户端 IP 的请求次数、来自您组织的请求次数，或可计费 flex 并发租约。可计费 flex 并发限制器默认为 20 个进行中的请求。请根据 `Retry-After` 中的秒数进行退避，通常认证洪水限制器为 60 秒，其他请求限制器为 5 秒。 | | `402` | `payment_required` | 此组织有逾期余额或未存档付款方式，因此可计费 flex 请求已暂停。免费路由（`default`、`priority`、`auto`）和所有 Anthropic 层级请求仍可正常工作。请在控制面板的[计费](/zh/billing)页面添加或更新银行卡，然后重试。这是唯一带有 `type: billing_error` 的代码。 | | `413` | `request_too_large` | 请求体超出了 FlexInference 的 1,000,000 字节限制，此限制会根据声明的 `Content-Length` 和实际流传输的字节数进行检查。大型内联 base64 文件是常见原因。请缩小有效负载，或指向托管 URL。 | | `400` | `no_byok_key` | 您的组织未配置 OpenAI 密钥。请在控制面板的“设置”->“API 密钥”下添加一个。BYOK 密钥以加密形式存储；如果存储的密钥存在但无法解密，请求将以 `500 internal_error` 失败，而不是此代码。您在 `provider` 链中命名的每个路由都需要其密钥：缺少密钥是配置错误，而不是瞬时故障，因此在任何上游调用之前就会被拒绝，并且永远不会回退到下一个路由。 | | `400` | `no_gemini_key` | 与 `no_byok_key` 相同，适用于 `gemini-*` 模型：您的组织未配置 Gemini 密钥。请在控制面板中添加一个。 | | `400` | `no_anthropic_key` | 与 `no_byok_key` 相同，适用于 `claude-*` 模型：您的组织未配置 Anthropic 密钥。请在控制面板中添加一个。 | | `400` | `no_bedrock_key` | 与 `no_byok_key` 相同，适用于 `provider` 链中的 `bedrock` 路由：您的组织未配置 Bedrock 密钥。Bedrock 通过 Amazon Bedrock 使用您自己的密钥提供 `claude-*` 模型；请在控制面板的“设置”->“API 密钥”下添加一个。链中任何位置的 `bedrock` 条目都需要密钥，因此在任何上游调用之前，缺少密钥的请求都会被拒绝。 | | `400` | `no_vertex_key` | 与 `no_byok_key` 相同，适用于 `provider` 链中的 `vertex` 路由：您的组织未配置 Vertex 密钥。Vertex 通过 Google Vertex AI 使用您自己的 express 密钥（`AQ.` 前缀）提供 `gemini-*` 模型；请在控制面板的“设置”->“API 密钥”下添加一个。链中任何位置的 `vertex` 条目都需要密钥，因此在任何上游调用之前，缺少密钥的请求都会被拒绝。 | | `400` | `missing_model` | `model` 字段缺失、为空或不是字符串。请添加一个非空字符串，例如 `"model": "gpt-5.5"`。 | | `400` | `missing_start_within` | 必需的 `start_within` 字段缺失，且未应用默认值。`start_within` 设置了您愿意等待请求启动的时间。请使用 `default`、`priority`、`auto`，或持续时间格式，例如 `HHh-MMm-SSs`，例如 `00h-00m-30s` 表示等待最多 30 秒。 | | `400` | `invalid_start_within` | `start_within` 不是字符串，不符合四种接受形式之一，或者解析出的持续时间超出了 5 秒到 600 秒（10 分钟）的允许范围。请匹配确切的格式，并将持续时间保持在 5 秒到 600 秒之间。例如，使用 `"start_within": "00h-00m-30s"` 表示 30 秒的窗口，或使用 `"start_within": "default"` 以跳过 flex 竞争。 | | `400` | `auto_unsupported_for_gemini` | 在 Gemini 模型上使用了 `start_within: "auto"`。Gemini 的层级只有 `flex`、`standard` 和 `priority`；没有 `auto` 可解析。请改用 `default`、`priority` 或持续时间。 | | `400` | `flex_unsupported_for_anthropic` | 向 `claude-*` 模型发送了持续时间 `start_within`（flex 竞争），但 Anthropic 没有 flex 层级可供竞争。FlexInference 不再对不适用的 flex 竞争静默提供标准层级。请使用层级 `start_within`（`default`、`priority`、`auto`）或省略它。 | | `400` | `flex_model_not_capable` | 向不在 flex 允许列表中的 OpenAI 或 Gemini 模型发送了持续时间 `start_within`。请使用层级 `start_within` 或选择支持 flex 的模型。 | | `400` | `service_tier_not_allowed` | 请求中包含了 `service_tier`。FlexInference 从 `start_within` 推导出层级；接受调用者提供的 `service_tier` 将需要覆盖它，因此路由器会拒绝该字段。请移除 `service_tier` 并通过 `start_within` 表达相同的意图。也适用于 `/v1/interactions` 和 `/v1/messages`。 | | `400` | `unsupported_parameter` | 提供商原生参数被发送到不同的提供商，或者规范的 Responses 字段没有目标提供商的映射。Chat 原生参数在 OpenAI 模型上可以传递，但在 Gemini 或 Claude 模型上会失败。Anthropic 原生参数在 Claude 模型上可以传递，但在 OpenAI 或 Gemini 模型上会失败，除了带有 base64 源的 `document` 和 `file` 内容块，它们可以转换为所有提供商。`cache_control`、引用和其他提供商原生参数仍然会跨提供商失败。请移除指定字段或选择其提供商拥有的模型；`error.param` 会准确指出是哪个字段。请参阅 [SDKs](/zh/sdks)。 | | `400` | `unsupported_generation_config` | 在 `/v1/interactions` 上，当目标是非 Gemini 模型时，设置了未映射的 `generation_config.*` 字段。Gemini 原生额外键在 Gemini 模型上可以传递。请移除指定字段或将目标设为 Gemini 模型。 | | `400` | `unsupported_tool` | `tools` 数组包含一个内置工具，该工具使模型发出非文本输出，目前是 `image_generation`。FlexInference 仅在所有端点上提供文本输出。请移除该工具条目；函数工具和 `web_search` 仍然受支持。 | | `400` | `unsupported_value` | Chat Completions `n` 被设置为 `1` 以外的值。底层的 Responses API 总是生成单个响应，因此 `n` 必须为 `1` 或省略。例如，发送 `"n": 1` 或省略 `n`。 | | `400` | `invalid_json` | 请求体不是语法有效的 JSON（`JSON.parse` 失败）。请修复语法；尾随逗号或未加引号的键是常见原因。 | | `400` | `invalid_body` | 请求体已解析为 JSON，但顶级值不是 JSON 对象。数组、字符串、数字、布尔值和 null 是无效的。请将您的字段封装在单个 `{...}` 对象中。 | | `400` | `invalid_stream` | `stream` 字段必须是 JSON 布尔值。FlexInference 不会强制转换非布尔值，包括字符串 `"true"`，因为这可能会选择错误的响应模式。请将 `stream` 作为真正的布尔值发送，例如 `"stream": true`，或省略它以获得非流式响应。 | | `400` | `invalid_retry` | `retry` 值无效。`retry` 是一个对象 `{ count, backoff?, jitter? }`，其中 `count` 是一个介于 1 到 5 之间的整数（FlexInference 在瞬时 429 或 5xx 错误时重试上游层级的次数），`backoff` 是 `"exponential"` 或 `"linear"`，`jitter` 是一个布尔值。此代码涵盖了 `count` 缺失或超出范围、`backoff` 值错误、`jitter` 非布尔值以及任何未知子键。请更正或移除该字段，例如 `"retry": {"count": 2}`。重试只会在响应提交之前重新命中已确定的层级；它绝不会在第一个字节、认证失败或客户端 4xx 错误之后重试。 | | `400` | `invalid_provider_chain` | 可选的 `provider` 数组格式错误：不是数组、为空、包含未知路由名称、重复或超过三个条目。每个条目必须是 `google`、`openai`、`anthropic`、`vertex` 或 `bedrock` 之一；元素 0 是主路由，其余是按顺序排列的同模型回退链。省略 `provider` 以使用模型的原生路由，或更正数组，例如 `["google", "vertex"]`。一个代码涵盖了所有格式错误的链原因，例如 `invalid_retry`；`error.message` 会指出具体的故障。 | | `400` | `provider_model_mismatch` | `provider` 链中的路由无法提供请求的模型。每个路由提供一个模型系列：`openai` 提供 GPT 和 o 系列模型，`google` 和 `vertex` 提供 Gemini，`anthropic` 和 `bedrock` 提供 Claude。请移除与此模型不匹配的路由，或将请求发送到该路由可以提供的模型，例如 `["anthropic"]` 用于 `claude-*` 模型。 | | `400` | `flex_unsupported_on_cloud` | 持续时间 `start_within`（flex 竞争）与云路由（`vertex` 或 `bedrock`）作为元素 0 一起发送，但云路由没有 flex 层级可供竞争。FlexInference 不会静默地为不适用的 flex 竞争提供默认层级。请使用层级 `start_within`（`default`、`priority` 或 `auto`）以将云路由作为普通标准调用运行，或将支持 flex 的直接路由（`openai` 或 `google`）放在 `provider` 的首位。 | | `400` | `bedrock_model_unavailable` | `bedrock` 路由没有此 slug 的 Amazon Bedrock 模型 ID，因此请求在任何上游调用之前就被拒绝。今天这意味着 `claude-opus-4-1`（已从 `bedrock` 路由中删除，因为 AWS 仅在美国发布；请改发给 `anthropic`）或任意未映射的 `claude-*` 文本。Bedrock 通过其 `global.` 推理配置文件提供所有映射的 Claude 模型，因此任何区域都可以访问已提供的模型；区域派生的地理位置（`us-*` -> `us.`，`eu-*` -> `eu.`，其他 -> `global.`）仅是未来发布没有 `global.` 配置文件的模型的休眠回退。这对于该 slug 是永久性的，而非瞬时。`provider` 中命名的每个路由都必须能够处理请求，因此即使链中的其他路由可以处理此模型，命名 `bedrock` 也会导致请求失败。请从 `provider` 中移除 `bedrock`，或将模型发送到可以提供它的路由。 | | `403` | `bedrock_model_access_denied` | Amazon Bedrock 拒绝了您的组织 Bedrock 密钥所关联的 AWS 账户的模型请求，FlexInference 会透传 Bedrock 自己的解释（`... is not available for this account`）。您的 Bedrock 密钥有效且正常工作：这是 AWS 账户上缺少每个模型的访问授权，而不是密钥问题，因此更换密钥无法解决。对于大多数 Claude 模型，请在 Amazon Bedrock 控制台的“模型访问”下授予模型权限。四个最新模型（`claude-sonnet-5`、`claude-fable-5`、`claude-opus-4-8`、`claude-opus-4-7`）还需要一次性账户设置，控制台授权不涵盖此项——即 `provider_data_share` 数据保留选择加入和模型协议，需使用管理员 AWS 凭证运行；请参阅[最新模型设置](/zh/models)。否则，请将模型发送到 `anthropic` 路由，或选择账户已有的模型。这是一个永久性的配置缺陷，因此它是 `403` 而不是可重试的 `502`。 | | `404` | `unknown_url` | 路径错误。请使用 `/v1/responses`、`/v1/chat/completions`、`/v1/interactions` 或 `/v1/messages`。 | | `405` | `method_not_allowed` | 路径存在，但 FlexInference 端点只接受 `POST`。请发送带有 JSON 主体的 `POST` 请求。 | | `499` | `client_closed_request` | 客户端在 FlexInference 完成响应之前断开连接，通常是由于关闭了标签页、取消了 fetch 请求或客户端超时。这不计为服务故障。如果您并非有意取消，请增加客户端超时时间并让请求完成。flex 请求合法地可能需要长达 10 分钟。 | | `500` | `internal_error` | FlexInference 在输入验证之外失败。请重试一次；如果问题持续存在，请联系支持人员并提供大致的时间戳和您的组织信息。 | | `500` | `server_misconfigured` | 必需的绑定或密钥缺失或格式错误，导致 FlexInference 无法验证调用者或解密 BYOK 密钥。这是服务器端部署故障，与 `internal_error` 不同，并非您的请求问题。请稍后重试，如果问题持续存在，请联系支持人员。 | | `502` | `upstream_stream_failed` | 上游提供商提交了响应，但其流在没有完成事件的情况下结束，或在流传输中途失败，且没有提供商错误可透传。这是 FlexInference 与提供商之间的瞬时上游或网络故障，并非您的请求问题。请重试一次。如果对某个模型持续存在此问题，则提供商或模型可能已降级；请尝试其他模型，或设置更短的 `start_within` 窗口，以便缓慢的尝试能更快地升级到您的标准层级。这与提供商本身返回的上游 `5xx` 错误不同，后者会以提供商的消息重新塑形到您的接口。 | | `502` | `upstream_unavailable` | FlexInference 在任何响应提交之前无法打开与上游提供商的连接（连接被拒绝，或 DNS、TLS 或网络失败）。这是上游或网络故障，并非您的请求问题。请重试一次；如果对某个模型持续失败，则提供商可能已宕机，请尝试其他模型。这与 `upstream_stream_failed` 不同，后者是响应已经开始。 | | `502` | `upstream_auth_failed` | 上游提供商拒绝了您的组织为其附加的 API 密钥（HTTP 401 或 403，在任何响应提交之前）。这不是您的 FlexInference 密钥失败；存储的提供商凭证缺少访问权限、已被撤销、已过期或以其他方式无效。请让组织管理员在控制面板的“设置”->“API 密钥”下更新附加的提供商密钥，然后重试。 | | `502` | `all_routes_failed` | `provider` 链中的所有路由在任何响应提交之前都瞬时失败（每次尝试的上游都返回 `429`、`5xx`、连接错误或超时），因此没有可回退的路由。这是上游或网络状况，并非您的请求问题，因此即使链本身已耗尽，也报告为 `502`。请重试一次；短暂的上游故障通常会清除。如果问题持续存在，请尝试不同的模型或将链缩短为当前健康的路由。 | | `503` | `usage_persistence_unavailable` | FlexInference 无法持久记录可计费请求的使用情况。请在使用情况持久化恢复后重试一次。 | | `504` | `upstream_timeout` | 上游提供商在 FlexInference 的上游超时之前未开始响应，因此请求在 FlexInference 和提供商之间被中止。这几乎总是瞬时提供商速度变慢或中断，并非您的请求问题，并报告为 `504` 而不是内部错误。请重试一次；如果对某个模型持续超时，则提供商可能已降级，请尝试其他模型，或者对于持续时间 `start_within`，设置更短的截止时间，例如 `00h-00m-30s`。 | `provider` 数组固定了您的路由。`google`、`openai` 和 `anthropic` 是 直接路由；`vertex` 和 `bedrock` 是云路由，分别在 Google Vertex AI 和 Amazon Bedrock 上提供 `gemini-*` 和 `claude-*` 模型。未配置密钥的云路由会返回 [`no_vertex_key`](/zh/errors#no_vertex_key) 或 [`no_bedrock_key`](/zh/errors#no_bedrock_key)，这与上述 [`no_gemini_key`](/zh/errors#no_gemini_key) 和 [`no_anthropic_key`](/zh/errors#no_anthropic_key) 的密钥缺失模式相同。`upstream_auth_failed` 涵盖了上游拒绝的任何附加提供商凭证，包括云路由。请参阅 [提供商路由](/zh/models)。 ## Flex 结果头部 成功的 `200` 响应在每个端点上都包含 Flex 结果头部，适用于流式和非流式调用。错误响应则使用错误体。 | 头部 | 含义 | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-flexinference-flex-requested` | 当调用者发送持续时间 `start_within` 时为 `true`；当调用者发送 `default`、`priority` 或 `auto` 时为 `false`。 | | `x-flexinference-flex-applied` | 仅当 flex 层级提供了响应时为 `true`。 | | `x-flexinference-flex-reason` | 机器可读的 flex 结果。请参阅下方的值。 | | `x-flexinference-provider-surface` | 提供商执行接口。值为 `openai.responses`、`openai.chat`、`gemini.interactions` 和 `anthropic.messages`。这不总是调用者端点。使用 OpenAI 模型调用 `/v1/chat/completions` 会报告 `openai.responses`，除非需要原生 Chat 透传，在这种情况下会报告 `openai.chat`。 | 实时 `x-flexinference-flex-reason` 值： | 原因 | 含义 | | ---------------- | ------------------------------------------------------------------------------ | | `not_requested` | 请求使用了 `default`、`priority` 或 `auto`，因此未请求 flex 竞争。 | | `flex_committed` | flex 竞争已提交。响应显示 `service_tier: "flex"` 和 `x-flexinference-flex-applied: true`。 | | `flex_lost_race` | 请求在支持 flex 的模型上使用了持续时间，但 flex 未在窗口内启动，请求回退到标准层级。 | 无法进行 flex 竞争的持续时间会返回 `400` （在 `claude-*` 模型上为 `flex_unsupported_for_anthropic`， 在不支持 flex 的 OpenAI/Gemini 模型上为 `flex_model_not_capable`）； 头部原因仅描述了已运行 flex 或未请求 flex 的请求。 ## 提供商错误 上游提供商错误使用与 FlexInference 错误相同的接口封装。FlexInference 保留提供商的状态和消息，然后将其在您调用的端点的封装中发出。提供商因参数错误返回的 `400`、因无效提供商密钥返回的 `401`，或标准尝试中的 `429` 速率限制，都会以该格式返回。您不会收到提供商的原始响应体。例如，调用 `/v1/messages` 时，OpenAI 模型错误会以 Anthropic 格式返回。FlexInference 特定的 `code` 和 `doc_url` 仅出现在 OpenAI 封装中；提供商错误会携带提供商的消息以及接口的 `type` 或 `status`。 在 OpenAI 接口上，根据 `error.code` 进行分支处理 FlexInference 特定的情况， 例如在 `no_byok_key` 时提示用户添加 BYOK 密钥。将未知代码视为普通的 OpenAI 错误。 ## 代码中的错误处理 OpenAI SDK 会在非 2xx 响应时抛出异常，并附带解析后的响应体。 ```python Python theme={null} from openai import APIStatusError try: resp = client.responses.create( model="gpt-5.5", input="hi", extra_body={"start_within": "00h-00m-30s"}, ) except APIStatusError as e: code = (e.body or {}).get("error", {}).get("code") if code == "no_byok_key": print("Add your OpenAI key in the dashboard.") else: raise ``` ```typescript Node theme={null} import OpenAI from "openai"; try { await client.responses.create({ model: "gpt-5.5", input: "hi", start_within: "00h-00m-30s", } as any); } catch (e) { if (e instanceof OpenAI.APIError && e.code === "no_byok_key") { console.log("Add your OpenAI key in the dashboard."); } else { throw e; } } ```