GPT 错误处理

本章节说明 「站点地址」 在请求出错时返回的统一错误结构，以及推荐的客户端处理方式。建议按本文设计重试与告警逻辑，以获得更稳定的接入体验。

本文以入站 /v1/chat/completions 为例进行说明。

统一错误结构

所有错误响应均规范为以下结构：

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

请以 error.type + HTTP 状态码 作为判定依据。message 仅用于辅助排查，其内容可能随上游变化，请勿据其做精确匹配。

错误类型一览（非流式）

error.type	HTTP 状态码	含义	建议处理
rate_limit_error	429	限流 / 并发受限	退避后重试，初始 1–2s，指数退避至约 30s
upstream_error	502 / 503	上游临时不可用或过载	退避后重试；502 短退避，503 适当拉长间隔并降低并发
api_error	503	服务暂不可用	退避后重试

同一 HTTP 状态码可能对应不同 error.type（例如 503 既可能是 upstream_error 也可能是 api_error），因此请始终结合 error.type 一起判断。

流式（stream）场景

在流式请求中，HTTP 响应头会在首个数据包发出时即固定为 200；此后即使发生错误，状态码也无法再变更。因此流式错误不会体现在 HTTP 状态码上，而是以 SSE 事件的形式出现在响应体中：

event: error
data: {"error":{"type":"upstream_error","message":"..."}}

处理建议：

1. 解析响应体而非依赖状态码：流式下需读取 SSE error 事件中的 error.type 进行判断。
2. 先按 error.type 归类：对应上文「错误类型一览」中的三类处理。
3. 如需细化退避节奏，可参考 message 关键词：
   • 含 overloaded → 视为过载，采用较长退避；
   • 含 temporarily unavailable → 视为临时不可用，采用较短退避。

推荐的重试策略

• 限流（rate_limit_error）：采用指数退避，避免短时间内重复冲击。
• 临时不可用 / 过载（upstream_error / api_error）：保留自动重试；遇过载时建议同时适当降低并发。
• 避免无上限重试：建议设置最大重试次数与总超时，持续失败时记录日志或触发告警。

上述退避数值为通用建议，可结合自身业务的延迟与并发特征调整。

需要协助时

若按本文处理后仍有较高错误率，请联系售后支持，并尽量提供：

• 问题发生的大致时间段；
• 出现的 error.type 与 HTTP 状态码；
• 请求示例（去除敏感信息后）：所用模型名称、是否为流式、关键参数。

携带上述信息可显著提升排查效率。