Errors

所有 API 错误均使用标准 HTTP 状态码返回。错误响应体为 JSON 格式，包含 error 对象。

错误响应格式

{
  "error": {
    "message": "Incorrect API key provided",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

字段	类型	说明
error.message	string	人类可读的错误描述
error.type	string	错误类型分类
error.param	string | null	引发错误的参数名
error.code	string	机器可读的错误码

常见错误码

状态码	错误类型	说明
400	invalid_request_error	请求参数格式错误或缺少必填字段
401	authentication_error	API Key 无效、缺失或格式错误
403	permission_error	无权限访问该资源或模型
404	not_found_error	请求的接口路径或模型不存在
429	rate_limit_error	请求频率超出限制或额度用尽
500	server_error	服务器内部错误
502	bad_gateway	上游模型提供商返回错误
503	service_unavailable	服务暂时不可用

400 Bad Request

请求参数有误。

{
  "error": {
    "message": "you must provide a model parameter",
    "type": "invalid_request_error",
    "param": "model",
    "code": null
  }
}

排查建议：

• 检查请求体 JSON 格式是否正确
• 确认所有必填参数已提供（如 model、messages）
• 确认参数值类型正确

401 Unauthorized

认证失败。

{
  "error": {
    "message": "Incorrect API key provided",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

排查建议：

• 检查 Authorization 请求头是否正确设置
• 确认 API Key 未过期或被删除
• 确认 API Key 格式正确（无多余空格）

403 Forbidden

无权限访问。

{
  "error": {
    "message": "You do not have access to this model",
    "type": "permission_error",
    "param": null,
    "code": "model_access_denied"
  }
}

排查建议：

• 确认 API Key 是否有该模型的访问权限
• 确认 IP 是否被限制
• 联系管理员检查权限配置

404 Not Found

资源不存在。

{
  "error": {
    "message": "The model `gpt-5` does not exist",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

排查建议：

• 检查 URL 路径是否正确
• 确认模型名称拼写正确
• 通过 GET /v1/models 查看可用模型

429 Rate Limit

频率或额度限制。

{
  "error": {
    "message": "Rate limit reached for requests",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

排查建议：

• 降低请求频率
• 使用指数退避重试
• 检查剩余额度
• 联系管理员提升限额

500 Internal Server Error

服务器内部错误。

{
  "error": {
    "message": "The server had an error while processing your request",
    "type": "server_error",
    "param": null,
    "code": null
  }
}

排查建议：

• 稍后重试
• 如果持续出现，联系管理员
• 检查是否为上游模型提供商的问题

502 Bad Gateway

上游网关错误。

{
  "error": {
    "message": "Bad gateway",
    "type": "server_error",
    "param": null,
    "code": "bad_gateway"
  }
}

排查建议：

• 上游模型提供商可能暂时不可用
• 尝试更换模型
• 稍后重试

503 Service Unavailable

服务不可用。

{
  "error": {
    "message": "Service is temporarily unavailable",
    "type": "server_error",
    "param": null,
    "code": "service_unavailable"
  }
}

排查建议：

• 服务可能正在维护
• 稍后重试
• 关注平台公告

指数退避重试示例

import time
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["API_KEY"],
    base_url=os.environ["BASE_URL"],
)

def chat_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=os.environ["MODEL"],
                messages=messages,
            )
            return response
        except Exception as e:
            if "429" in str(e) and attempt < max_retries - 1:
                wait_time = 2 ** attempt
                print(f"Rate limited, waiting {wait_time}s...")
                time.sleep(wait_time)
                continue
            raise

result = chat_with_retry([
    {"role": "user", "content": "Hello"}
])
print(result.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: process.env.BASE_URL,
});

async function chatWithRetry(messages, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await client.chat.completions.create({
        model: process.env.MODEL,
        messages,
      });
      return response;
    } catch (error) {
      if (error.status === 429 && attempt < maxRetries - 1) {
        const waitTime = Math.pow(2, attempt) * 1000;
        console.log(`Rate limited, waiting ${waitTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      throw error;
    }
  }
}

const result = await chatWithRetry([
  { role: 'user', content: 'Hello' }
]);
console.log(result.choices[0].message.content);