错误码
识别 Sublyx API 错误，决定是否修正请求、充值或重试。
先根据 HTTP 状态码判断错误类别，再读取响应体中的 error、code、type 或 message 字段。日志中应保留请求标识，但必须遮蔽 API Key 和敏感内容。
常见状态码
| 状态码或错误 | 含义 | 建议 |
|---|---|---|
400 Bad Request | JSON、参数或模型配置无效 | 检查请求体和必填字段 |
API_KEY_REQUIRED | 未提供 API Key | 添加认证请求头 |
401 Unauthorized | Key 无效、过期或已停用 | 检查 Key 与请求头格式 |
402 Payment Required | 账户余额不足 | 登录控制台充值 |
404 Not Found | 路径或模型不存在 | 检查 Base URL、端点与模型 ID |
429 Too Many Requests | 触发速率或并发限制 | 退避后重试并控制并发 |
500 Internal Server Error | 服务端内部异常 | 短暂退避后重试 |
502 Bad Gateway | 上游响应异常 | 重试或切换模型 |
503 Service Unavailable | 服务暂时不可用 | 退避重试并启用降级 |
504 Gateway Timeout | 上游调用超时 | 缩短输入、调整超时或重试 |
错误响应示例
{
"error": {
"type": "invalid_request_error",
"code": "API_KEY_REQUIRED",
"message": "API key is required"
}
}不同兼容协议的字段可能不同，不要只匹配错误文案。优先使用 HTTP 状态码与稳定的错误类型。
是否应该重试
| 错误类型 | 自动重试 |
|---|---|
| 参数错误、认证失败、余额不足 | 否，先修正配置 |
| 速率限制 | 是，读取等待信息并指数退避 |
500、502、503、504 | 是，限制次数并加入随机抖动 |
| 网络中断 | 视幂等性决定 |
const retryable = new Set([429, 500, 502, 503, 504]);
async function wait(attempt: number) {
const base = Math.min(1000 * 2 ** attempt, 10_000);
const jitter = Math.random() * 300;
await new Promise((resolve) => setTimeout(resolve, base + jitter));
}流式请求的重试
流中断后重试可能产生重复内容。应用需要记录已接收片段、请求状态和幂等上下文，避免简单地从头追加。