GPT-6 Astra API 错误：15个常见问题及解决方法

让API事故恶化的最快方式是对每个错误都进行重试。格式错误的模式不会因为退避策略而自行修复，透支的信用余额也不会因为工作进程多尝试十次而恢复。通过HTTP状态码、SDK类、error.type，尤其是error.code来诊断错误。

安全的错误处理器

try {
  return await client.responses.create({
    model: "gpt-6-astra",
    输入
  });
} catch (error) {
  if (error instanceof OpenAI.APIConnectionError) {
    // Network, proxy, TLS, DNS or firewall path.
  } else if (error instanceof OpenAI.RateLimitError) {
    // Inspect code and Retry-After before deciding to retry.
  } else if (error instanceof OpenAI.APIError) {
    console.error(error.status, error.message, error.code);
  } else {
    抛出错误；
  }
}

记录请求ID、时间戳和时区、模型、端点、状态、代码、重试次数以及经过清理的负载特征。默认情况下，绝不记录API密钥或机密提示内容。

1. 400 错误请求

载荷格式错误或不兼容：字段错误、缺少输入、工具模式无效、组合不受支持或内容编码错误。请阅读消息，与当前的 Responses 参考文档进行比对，并添加契约测试。不要对未更改的输入进行重试。

2. 401 身份验证错误

密钥或令牌无效、已过期、已撤销或发送错误。请确认密钥注入和项目环境。轮换已暴露的密钥；调试时切勿打印它们。

3. 401 组织或项目不正确

即使密钥有效，也可能指向错误的作用域。请检查项目配置以及任何明确指定组织/项目的标头。确保密钥、资源和结算作用域保持一致。

4. 401 IP未授权

请求来源与配置的允许列表不匹配。请从批准的出口IP发送，或通过授权管理更新允许列表。从同一来源重试无效。

5. 403 权限被拒绝或区域不受支持

调用者无权访问该资源、模型或区域。请验证项目角色、模型可用性、资源所有权以及支持的国家/地区规则。不要在内部日志中将权限问题伪装为“未找到”。

6. 404 未找到

响应、对话、向量存储、文件或其他标识符错误、过期或无法访问。请确认确切的ID和项目。如果面向用户，请避免泄露该用户范围之外的资源存在。

7. 409 冲突

另一个请求同时更改了资源。请重新加载当前状态，针对新版本重新应用预期更改，并使用乐观锁定或幂等性。盲目立即重试可能会重复冲突。

8. 422 无法处理的实体

格式在语法上可接受，但服务无法处理。请验证大小、编码、文件状态和字段组合。官方表格建议重试，但首先应排除确定性原因。

9. 429 请求或令牌速率限制

控制流量节奏，并在存在 Retry-After 时遵守该指令。否则，使用带抖动的有界指数退避策略。协调各工作节点间的重试预算，避免形成惊群效应。减少冗余调用和大量令牌突发。

10. 429 `slow_down`

这是一个速率限制信号：即使总体限制看似充足，流量增长仍过快。请遵循 Retry-After 指示，降低请求速率，再逐步增加。OpenAI 当前指南给出经验法则：达到每分钟一百万输入令牌后，每15分钟增长不应超过50%；实际触发条件因模型和情况而异。

11. 429 信用额度、消费或使用限制

错误码包括 credit_balance_exhausted（信用额度耗尽）、organization_spend_limit_exceeded（组织消费限额超支）、project_spend_limit_exceeded（项目消费限额超支）和 organization_usage_limit_exceeded（组织使用量限额超支）。这些情况需要充值或调整限额。重试无法恢复访问权限。请立即通知所有者并快速失败。

12. 500 内部服务器错误

在短暂等待后，使用有限预算重试，若失败持续则检查状态页面。记录请求ID以供支持。对于状态变更的工作流，在重放整个请求前，先协调工具副作用。

13. 503 模型过载

文档中记录的类型/代码为 service_unavailable_error / server_is_overloaded。请遵循 Retry-After 指示，若无此字段则主动退避。请注意，当前 Python SDK 指南将 429 的 RateLimitError 与 503 的 InternalServerError 区分开来；如果你的过载逻辑此前将所有容量问题都视为 429，请同时捕获这两种错误。

14. 连接或超时错误

APIConnectionError 可能表示网络、代理、TLS 证书、DNS 或防火墙问题。APITimeoutError 表示已超过截止时间。重试安全的读取操作，检查企业代理设置，并避免禁用 TLS 验证。对于写入操作，需在重试前确定操作是否已执行。

15. WebSocket 状态与流式传输失败

previous_response_not_found 表示引用的状态无法解析；官方指南建议重新发送完整的输入上下文，并将 previous_response_id 设为 null。websocket_connection_limit_reached 反映了 60 分钟连接限制；请打开新连接并继续。同时处理 response.failed、response.incomplete 和传输 error 事件，而不是假设套接字关闭即表示完成。

重试矩阵

| 类别 | 是否重试未更改项？ | 正确操作 | | 400/401/403/404 | 否 | 修复请求、身份、权限或 ID 问题 | | 409 | 协调后 | 安全地重新加载版本并应用 | | 422 | 有时 | 先检查确定性原因 | | 429 速率/减速 | 是，有界 | 遵循 Retry-After；退避与抖动 | | 429 计费/限制 | 否 | 添加积分或更改已批准的限额 | | 500/503 | 是，有界 | 退避、状态检查、保留请求ID | | 连接/超时 | 取决于 | 重试读取；协调写入 |

限制重试次数和总重试时间。在广泛故障期间使用断路器，对于需要操作员审查的任务使用死信路径。重试应可观测，而非隐藏在堆叠的SDK和应用程序循环中。