LLM 网关错误分类法：区分身份验证、配额、提供商和安全故障

LLM 网关错误分类法是区分受控事件和昂贵的重试风暴的关键。网关不应将每次失败的模型调用都视为同一种提供商错误。无效凭据、配额耗尽、提供商过载、格式错误的请求、安全拒绝、超时和客户端取消都需要不同的恢复路径。

常见的错误是将每次失败都发送到相同的重试和回退循环中。这可能会隐藏已吊销的密钥，耗尽支出上限，将不安全的内容路由到其他提供商，或者在流式响应已经开始后重复工作。一个实用的 LLM 网关错误分类法为工程、产品和财务团队提供了一种共享语言，用于描述发生了什么以及网关接下来应该做什么。

Flatkey 符合这种运营模式，因为其当前的公共网站将产品定位为用于模型访问、路由、计费、使用分析和运营控制的单一网关界面。在选择重试、排队、回退或故障关闭行为之前，请使用该共享界面对故障进行分类。

LLM 网关错误分类法一览表

从类别开始，而不仅仅是 HTTP 状态。相同的状态族在不同的提供商、SDK 和端点形态中可能意味着不同的事情。

这个 LLM 网关错误分类法是特意面向操作的。它不仅仅是为仪表板标记错误。它决定了系统何时可以花费更多令牌，何时必须要求所有者修复状态，以及何时应该停止。

重试前先分类

官方提供商文档支持区分这些类别。OpenAI 的错误指南区分了无效身份验证、不正确的 API 密钥、IP 允许列表失败、速率限制、配额或计费耗尽、服务器错误、过载、SDK 连接错误、SDK 超时、格式错误的请求、权限拒绝和速率限制异常。其速率限制指南建议使用随机指数退避，但也指出失败的请求仍计入每分钟的限制。

Anthropic 的错误文档区分了 invalid_request_error、authentication_error、permission_error、not_found_error、request_too_large、rate_limit_error、api_error 和 overloaded_error。Anthropic 还记录了带有 retry-after 指南的 429 速率限制，其停止原因指南包括将 refusal 作为模型级别的停止条件。

Gemini 故障排除将身份验证和权限故障与 429 RESOURCE_EXHAUSTED、500 内部错误和 503 不可用分开映射。Gemini 速率限制文档描述了请求、令牌、每日请求和支出维度。Gemini 安全设置还公开了提示阻止、候选 finishReason 和 safetyRatings，包括当响应内容被阻止时的 finishReason 为 SAFETY。

这些证据引出了一条简单的规则：LLM 网关错误分类法应在网关选择操作之前，将特定于提供商的信号规范化为决策字段。

身份验证和权限故障

身份验证和权限故障应立即停止。重试错误的密钥或被禁止的项目通常只会增加噪音，而不会改变结果。

将这些信号规范化为身份验证类别：

在网关中，身份验证错误应包括 owner_key、credential_id、project_id、provider、endpoint_family、requested_model 和 route_id。避免记录原始密钥。事件应能回答哪个密钥失败、哪个路由尝试了调用以及谁可以修复它。

对于身份验证故障，回退通常是错误的做法。如果团队尚未批准某个提供商，静默切换到另一个提供商可能会绕过采购、数据边界或模型策略。受控的响应应该是明确的故障、所有者警报和修复路径。

配额和速率限制故障

配额和速率限制故障是受模糊重试逻辑影响最严重的类别。一个 429 错误可能意味着突发流量调整、每分钟请求限制、每分钟令牌限制、每日请求限制、月度预算耗尽、预付信用额度耗尽或基于支出的限制。这些情况没有共同的恢复路径。

使用此 LLM 网关错误分类法进行配额决策：

关键是要区分临时流量调整和预算耗尽。当提供商要求您放慢速度时，退避会有所帮助。当账户没有信用额度或作业不符合可用的令牌预算时，退避则无济于事。

当您需要更深入的重试清单时，请将本节与 Flatkey 的 AI API 重试策略结合使用。在日志中保持重试尝试可见，以便财务和运营部门可以看到重复的令牌支出。

提供商和传输故障

提供商和传输故障与配额故障不同。它们意味着请求可能有效，密钥可能有效，预算可能可用，但路由无法完成调用。

常见信号包括：

提供商回退在这里可能很有用，但需要一个约定。回退路由必须保留端点形态、工具、结构化输出需求、上下文窗口、数据边界、模型批准和成本上限。如果流式传输已经发出了可见的令牌，更安全的行为通常是停止并显示一个受控的故障，而不是拼接来自另一个路由的输出。

使用流式 AI API 可靠性进行流式特定恢复，并在将提供商错误转变为自动路由更改之前使用模型回退评估。

请求和验证失败

请求和验证失败通常不是提供商事件。它们意味着调用者发送了端点无法处理的内容。

示例包括缺少必填字段、格式错误的 JSON、不支持的参数、错误的端点系列、无效的模型 ID、上下文过长、不支持的工具模式、不兼容的模态，或不符合端点合同的文件/图像/视频输入。

网关应记录以下字段：

不要重试未更改的验证失败。要么将请求转换为有效形态，要么返回一个面向开发人员的错误，指明要修复的字段。当网关支持多个端点系列时，验证错误尤其重要，因为一个请求可能对一个提供商有效，而对另一个提供商无效。

安全和策略失败

安全和策略失败需要单独分类，因为重试和回退可能会意外削弱防护栏。安全拒绝不是提供商停机。审核阻止不是配额耗尽。被阻止的输出不是持续采样直到网关找到发出违禁内容的路由的理由。

将这些信号规范化为安全类别：

实践规则很简单：LLM 网关错误分类法绝不应将安全问题视为可恢复的提供商中断。只有当回退路由保留相同或更严格的安全策略，并且目标是完成任务的安全版本，而不是绕过阻止时，回退才是可接受的。

规范化的错误记录

一个有用的 LLM 网关错误分类法将特定于提供商的失败转化为一个持久的记录。

不要将此记录简化为单个字符串，例如“LLM 调用失败”。该字符串不足以决定是轮换密钥、等待、充值、回退、修改提示还是停止。

一个简单的 TypeScript 分类器

分类器不需要在第一天就了解每个提供商的详细信息。从明确的存储桶和保守失败的默认值开始。

type ErrorClass =
  | "auth"
  | "quota"
  | "provider"
  | "request"
  | "safety"
  | "cancelled"
  | "unknown";

type GatewayErrorInput = {
  httpStatus?: number;
  providerErrorType?: string;
  providerErrorCode?: string;
  finishReason?: string;
  stopReason?: string;
  clientCancelled?: boolean;
  timeout?: boolean;
};

function classifyGatewayError(error: GatewayErrorInput): ErrorClass {
  const type = (error.providerErrorType || "").toLowerCase();
  const code = (error.providerErrorCode || "").toLowerCase();
  const stop = (error.stopReason || "").toLowerCase();
  const finish = (error.finishReason || "").toLowerCase();

  if (error.clientCancelled) return "cancelled";

  if (error.httpStatus === 401 || error.httpStatus === 403) return "auth";
  if (type.includes("auth") || type.includes("permission")) return "auth";
  if (code.includes("invalid_api_key") || code.includes("ip_not_authorized")) {
    return "auth";
  }

  if (error.httpStatus === 429) return "quota";
  if (type.includes("rate_limit") || code.includes("quota")) return "quota";
  if (code.includes("resource_exhausted")) return "quota";

  if (stop === "refusal" || finish === "safety") return "safety";
  if (code.includes("moderation") || code.includes("blocked")) return "safety";

  if (error.httpStatus === 400 || error.httpStatus === 422) return "request";
  if (type.includes("invalid_request") || type.includes("bad_request")) {
    return "request";
  }

  if (error.timeout) return "provider";
  if ([500, 502, 503, 504, 529].includes(error.httpStatus || 0)) {
    return "provider";
  }
  if (type.includes("overloaded") || type.includes("api_error")) {
    return "provider";
  }

  return "unknown";
}

仅将此用作起点。生产分类器应将提供商特定的映射保留在配置、测试装置和事件审查中，而不是仅埋藏在应用程序代码中。

运行手册：重试、排队、回退或故障关闭

一旦类别已知，网关就可以选择操作。

此表是 LLM 网关错误分类法的操作中心。它告诉网关何时可以安全地执行更多工作，以及何时更多工作会带来风险。

如何在 Flatkey 中应用此分类法

将此分类法用作发布清单，而不是一次性的仪表板项目。

1. 选择一个工作流，例如支持聊天、批量提取、评估作业或代码助手流量。
2. 为该工作流定义允许的端点系列、模型、回退路由和成本上限。
3. 将提供商错误规范化为上述字段。
4. 使身份验证和权限故障对所有者可见且不可重试。
5. 将临时速率限制与配额、支出和每日限额耗尽分开。
6. 在更改提供商或模型之前，需要签订回退合同。
7. 将安全拒绝和审核视为策略结果，而不是提供商中断。
8. 在任何重试或回退之前记录部分输出状态。
9. 在扩展到更多工作流之前，在 Flatkey 中审查使用情况和路由证据。
10. 将运行手册链接到 Flatkey 定价，以便操作员可以验证当前目录和成本概况。

Flatkey 于 2026 年 7 月 3 日的公开定价 API 快照返回了 45 个模型行、6 个供应商 ID，并支持包括 openai、anthropic、gemini 和 image-generation 在内的端点系列。请仅将这些视为过时的源事实。在生产发布前，应重新检查模型的可用性、价格和路由行为。

常见问题解答

什么是 LLM 网关错误分类法？

LLM 网关错误分类法是针对模型-提供商流量的一组规范化故障类别。它区分了身份验证、配额、提供商、请求、安全和取消故障，以便网关可以选择重试、排队、回退或故障关闭行为。

为什么不重试每个 LLM API 错误？

重试每个错误可能会使事件恶化。它可能会放大速率限制，在配额耗尽后花费更多令牌，隐藏凭据失败，复制部分输出，或绕过安全阻止。该分类法决定了何时才真正允许重试。

安全拒绝是否应触发回退？

默认情况下不应触发。安全拒绝、审核阻止、提示阻止和 finishReason: SAFETY 应被视为策略结果。绝不应使用回退来寻找更弱的安全路由。

LLM 网关应如何对配额故障进行分类？

将临时速率调整与耗尽的支出、预付信用、每日限制、令牌限制和项目限制分开。临时调整可以使用有界退避或队列。耗尽的预算通常会故障关闭，直到所有者批准更多容量。

Flatkey 如何帮助实现 LLM 网关错误分类法？

Flatkey 为团队提供了一个统一的网关界面，用于模型访问、路由、计费、使用分析和操作控制。使用它来将规范化的错误类别与所有者密钥、端点系列、请求的模型、服务的模型和使用证据联系起来。

从一个工作流开始，定义您的 LLM 网关错误分类法，然后获取密钥，并在生产流量依赖自动恢复之前测试身份验证、配额、提供商、请求、安全和取消情况。