错误 - FlexInference

错误使用您调用的端点的封装。/v1/responses 和 /v1/chat/completions 返回 OpenAI 格式的错误。/v1/messages 返回 Anthropic 格式的错误。/v1/interactions 返回 Google 格式的错误。FlexInference 错误和上游提供商错误遵循相同的规则，因此每个端点都有一种错误格式。遇到 5xx 错误或超时？请首先查看 status.flexinference.com。它显示了 API、网站、文档和 MCP 服务器的实时运行状态，以及任何正在处理的事件。在 /v1/responses 和 /v1/chat/completions 上，错误使用 OpenAI 封装：

{
  "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 <key>`.",
    "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 格式：

{
  "type": "error",
  "error": { "type": "authentication_error", "message": "..." }
}

{ "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 <key>`。请发送 `Authorization: Bearer <your key>`。
`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 层级请求仍可正常工作。请在控制面板的计费页面添加或更新银行卡，然后重试。这是唯一带有 `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。
`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 凭证运行；请参阅最新模型设置。否则，请将模型发送到 `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 或 no_bedrock_key，这与上述 no_gemini_key 和 no_anthropic_key 的密钥缺失模式相同。upstream_auth_failed 涵盖了上游拒绝的任何附加提供商凭证，包括云路由。请参阅提供商路由。

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 响应时抛出异常，并附带解析后的响应体。

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

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;
  }
}

快速开始

概念

使用 API

常见问题

错误

FlexInference 代码

Flex 结果头部

提供商错误

代码中的错误处理

​FlexInference 代码

​Flex 结果头部

​提供商错误

​代码中的错误处理

FlexInference 代码

Flex 结果头部

提供商错误

代码中的错误处理