指南OneMux

如何安全诊断 OpenAI API 身份验证、速率限制、超时和响应格式错误

这是一份注重隐私的实用指南,介绍如何诊断 OpenAI API 身份验证、请求限流、超时和响应格式错误,同时避免泄露凭据或用户数据。

AI

摘要 · TL;DR

排查 OpenAI API 故障时,最安全的做法是在重试前先对故障分类。身份验证错误通常需要修正密钥、组织、项目或 IP 配置;速率和额度错误需要调整请求频率或进行管理设置;超时可能是暂时性的;响应格式错误则应作为传输、代理或解析故障单独排查。记录诊断元数据,不要记录凭据或未经处理的用户内容。

核心要点

  • 不要把 401 身份验证失败、账单或额度问题当作暂时性网络错误来重试。
  • 对于 429 限流和 503 过载响应,如果存在 Retry-After,应遵循其要求并采用有上限的指数退避。
  • 不要将 API 密钥放入源代码、日志、异常消息或客户端应用中。
  • 将非 JSON 响应或 JSON 解析失败视为独立的传输或代理问题,并且只收集经过脱敏且长度受限的诊断信息。
  • 升级反馈持续存在的问题时,请提供模型、错误代码、时间戳、时区和经过清理的请求详情。
文章目录 (7)

将 OpenAI API 故障区分为配置错误、容量错误、网络故障和响应解析失败,会更容易找到解决办法。诊断时首先要问:重试是否可能改变结果?

重试通常无法解决 401 错误。由请求速度导致的 429 错误可能会在降低请求频率后缓解;但如果 429 是因为额度耗尽或支出限额已达上限,就需要调整账户或项目设置。超时可能只是暂时性的,但反复超时也可能意味着网络、代理或请求大小存在问题。

以下操作流程使用 JavaScript 和 OpenAI 官方库中的相关概念,详情请参阅 OpenAI 错误代码指南。这些代码仅用于说明模式,并非经过测试的生产环境集成方案。

开始排查前:保护凭据和用户数据

重现错误之前,请先做好以下准备:

  • 将 API 密钥存储在服务端密钥管理器或环境变量中。切勿将密钥放入浏览器代码、移动应用、源代码管理系统或支持工单。
  • 记录请求时间戳、端点类别、模型标识符、HTTP 状态码,以及可用的结构化错误代码。
  • 不要记录 Authorization 请求头、完整请求正文、未经处理的响应正文,或包含个人数据的提示词。
  • 如果诊断确实需要提示词,请记录经过脱敏的样本或稳定的内部请求标识符,而不要保存原始文本。
  • 限制诊断数据的长度。代理可能返回很大的 HTML 错误页面,上游错误也可能包含你原本不打算留存的数据。

一条实用的运维原则是:让日志说明哪里出了问题、发生了什么,但不要记录用户说了什么或如何进行身份验证。

优先诊断 401 身份验证失败

文档列出的 401 情况包括身份验证无效、API 密钥错误、缺少组织成员资格,以及 IP 地址未获授权。403 则可能表示所在国家、地区或属地不受支持。

请按以下顺序检查:

  1. 确认服务器读取的是预期的密钥,并检查密钥是否被截断、过期、撤销或替换。
  2. 确认请求发送到了预期的 API 端点和项目。
  3. 如果配置使用了组织标识符或 IP 允许列表,请核对二者是否与项目配置一致。
  4. 检查请求是否来自开发环境、容器或托管环境中的其他出口 IP。
  5. 分享日志前,先从调试输出中移除所有凭据值。

不要对 401 或 403 错误启用自动重试。重复发送使用相同无效凭据的请求会产生噪声,也可能增加事件分析的难度。修正配置后,再发送新请求。

区分 429 限流与额度、账单问题

并非所有 429 都意味着“稍后重试即可”。OpenAI 指南区分了以下几种情况:

故障类别可能的处理方式是否自动重试?
达到速率限制降低请求频率;如果存在 Retry-After,则遵循其要求可以,但需设置限制
slow_down降低请求速率,并逐步提高可以,但需谨慎
余额耗尽充值不可以
组织或项目支出限额调整相应限额不可以
组织使用限额申请提高已批准的限额或联系支持团队不可以

重试循环应检查 HTTP 状态码和具体错误代码,而不是将所有 429 一概而论。请设置最大尝试次数,并采用指数退避和随机抖动,避免多个工作进程同时重试。如果存在 Retry-After,应优先遵循该等待时长,但仍需受你设定的最长等待时间约束。

还要考虑 503 响应。源文档将模型过载标记为 server_is_overloaded,并建议在重试前遵循 Retry-After(如果存在)。在 Python 库中,过载可能表示为 InternalServerError,而 429 响应使用 RateLimitError;处理程序不应假定过载总是以 429 的形式返回。

排查超时和连接故障

官方 Python 库将请求超时的情况记为 APITimeoutError,将连接问题记为 APIConnectionError。常见的排查范围包括:

  • **收到响应前超时:**检查客户端超时设置、网络路由、代理、防火墙和请求大小。
  • **连接失败:**检查 DNS、TLS 证书、出站防火墙规则和代理配置。
  • **反复出现服务端故障:**查看服务状态页,并保留经过脱敏的时间戳以供支持团队排查。

超时并不能证明服务器没有处理该请求。如果重复执行会造成影响,应设计应用逻辑,确保重试后可以安全核对处理结果;例如,可将操作关联到你自己的请求记录。不要通过无限延长超时时间或不设上限地重试来解决超时问题。

处理格式错误的响应,同时避免泄露内容

“响应格式错误”可能指几种不同的问题:无效请求导致 BadRequestError、响应不符合预期架构,或代理返回了 HTML 或截断的数据,而不是 JSON。OpenAI 指南将 BadRequestError 描述为请求格式错误或不完整,并建议检查必需参数、编码、格式和大小。

对于原始 HTTP 客户端或中间件,请分别进行以下检查:

  1. 解析前核实 HTTP 状态码和 Content-Type。
  2. 在受保护的代码块中解析 JSON。
  3. 使用响应前先验证必需字段是否存在。
  4. 如果策略允许,只记录状态码、内容类型、响应长度,以及经过脱敏且长度受限的片段。
  5. 切勿在解析错误消息中包含 API 密钥、完整提示词或完整响应。

示意性封装可以这样编写:

async function parseSafeResponse(response) {
  const contentType = response.headers.get("content-type") || "";
  const body = await response.text();

  if (!contentType.toLowerCase().includes("application/json")) {
    throw new Error(`Unexpected response type: ${contentType}; length=${body.length}`);
  }

  try {
    return JSON.parse(body);
  } catch {
    throw new Error(`Invalid JSON response; length=${body.length}`);
  }
}

此示例有意不在抛出的错误中包含请求正文。生产环境中,应根据端点添加适当的架构验证,并仅通过受控且经过隐私审查的诊断流程保留原始数据。

注重隐私的错误处理模式

官方 JavaScript 示例会区分连接错误、速率限制错误和更广泛的 API 错误。可以在此基础上扩展,在不打印机密或用户输入的前提下对错误进行分类:

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

try {
  const response = await client.responses.create({
    model: process.env.OPENAI_MODEL,
    input: "Redacted diagnostic input"
  });

  console.log({ ok: true, hasOutput: Boolean(response.output_text) });
} catch (error) {
  const details = {
    name: error?.name,
    status: error?.status,
    code: error?.code
  };

  if (error instanceof OpenAI.AuthenticationError) {
    console.error("Authentication failed", details);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("Rate limit or quota response", details);
  } else if (error instanceof OpenAI.APIConnectionError) {
    console.error("Connection failed", details);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API error", details);
  } else {
    console.error("Unexpected local error", { name: details.name });
  }
}

请根据你部署的 SDK 版本,核实类名和端点行为。不要假定每个兼容服务商的端点都支持所有 SDK 参数或响应字段。

何时升级反馈

对于持续存在的故障,OpenAI 指南建议提供模型、错误消息和代码、请求数据和请求头、时间戳、时区及其他相关详情。先清理这些信息:替换凭据、移除 Cookie、对个人数据脱敏,并尽可能概述请求正文。切勿在公开论坛发布敏感信息。

实际处理原则很简单:修正身份验证和额度问题;遇到限流和过载时退避;检查超时涉及的网络边界;排查解析失败时避免留存私人数据。

常见问题

每个 OpenAI 429 响应都应该重试吗?

不应该。对于请求速率和 slow-down 响应,可以谨慎地采用退避重试;如果存在 Retry-After,则应遵循其要求。额度耗尽、支出限额或组织使用限额问题无法通过重试解决。

为什么 OpenAI 过载错误有时会以 503 而不是 429 的形式出现?

OpenAI 错误指南将模型过载记录为带有 server_is_overloaded 代码的 503。错误处理程序应同时检查状态码和错误代码,而不要假定过载总是速率限制响应。

OpenAI 身份验证失败时应该记录哪些信息?

记录时间戳、环境、端点类别、状态码和经过脱敏的错误代码。不要记录 API 密钥、Authorization 请求头、完整请求正文或未经处理的用户提示词。

如何排查无效 JSON 响应?

解析前检查 HTTP 状态码和 Content-Type;如果策略允许,只收集长度受限且经过脱敏的诊断信息;同时检查代理或中间件是否返回了 HTML、截断了数据或更改了响应。

相关文章