API
错误处理
本指南介绍 BYOKS API 的错误码和处理方式。
错误响应格式
{
"error": {
"message": "错误描述信息",
"type": "error_type",
"code": "error_code",
"param": "相关参数（如有）"
}
}HTTP 状态码
| 状态码 | 说明 |
|---|---|
200 | 成功 |
400 | 请求参数错误 |
401 | 认证失败 |
403 | 权限不足 |
404 | 资源不存在 |
429 | 请求过多 |
500 | 服务器错误 |
502 | Provider 错误 |
503 | 服务暂不可用 |
错误码详解
400 Bad Request
请求参数有误：
{
"error": {
"message": "Invalid value for 'model': 'invalid-model' is not a valid model ID",
"type": "invalid_request_error",
"code": "invalid_model",
"param": "model"
}
}常见原因：
- 模型 ID 不正确
- 缺少必填参数
- 参数格式错误
解决方法：检查请求参数是否正确。
401 Unauthorized
认证失败：
{
"error": {
"message": "Invalid API key provided",
"type": "authentication_error",
"code": "invalid_api_key"
}
}常见原因：
- API Key 无效
- API Key 已过期
- 未提供认证信息
解决方法：检查 API Key 是否正确。
403 Forbidden
权限不足：
{
"error": {
"message": "You don't have access to this model",
"type": "permission_error",
"code": "model_not_available"
}
}常见原因：
- 未配置该模型的 Provider
- 账户被限制
解决方法：检查是否配置了相应的 Provider。
429 Too Many Requests
请求过多：
{
"error": {
"message": "Rate limit exceeded. Please slow down.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}常见原因：
- 超过每分钟请求限制
- 超过并发连接数
解决方法：降低请求频率，或升级套餐。
502 Bad Gateway
Provider 返回错误：
{
"error": {
"message": "The upstream provider returned an error",
"type": "provider_error",
"code": "provider_error",
"provider": "openai"
}
}常见原因：
- Provider 服务异常
- Provider API Key 无效
- Provider 配额用完
解决方法：检查 Provider 状态和配置。
503 Service Unavailable
服务暂不可用：
{
"error": {
"message": "All providers are currently unavailable",
"type": "service_error",
"code": "no_available_provider"
}
}常见原因：
- 所有配置的 Provider 都不可用
- 服务维护中
解决方法：等待服务恢复，或配置更多 Provider 作为备用。
错误处理示例
TypeScript
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://api.byoks.com/v1',
apiKey: 'your-byoks-key',
});
try {
const response = await client.chat.completions.create({
model: 'gpt-4o',
messages: [{ role: 'user', content: '你好' }],
});
console.log(response.choices[0].message.content);
} catch (error) {
if (error instanceof OpenAI.APIError) {
console.error('API 错误:', error.status, error.message);
if (error.status === 429) {
// 速率限制，等待后重试
await sleep(1000);
// 重试逻辑...
} else if (error.status === 502) {
// Provider 错误，尝试其他模型
// 重试逻辑...
}
} else {
console.error('网络错误:', error);
}
}Python
from openai import OpenAI, APIError, RateLimitError
import time
client = OpenAI(
base_url="https://api.byoks.com/v1",
api_key="your-byoks-key",
)
try:
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)
except RateLimitError:
print("速率限制，等待后重试")
time.sleep(1)
# 重试逻辑...
except APIError as e:
print(f"API 错误: {e.status_code} - {e.message}")重试策略
建议的重试策略：
| 错误类型 | 是否重试 | 策略 |
|---|---|---|
| 400 Bad Request | 否 | 修复请求参数 |
| 401 Unauthorized | 否 | 检查 API Key |
| 429 Rate Limit | 是 | 指数退避重试 |
| 500 Server Error | 是 | 等待后重试 |
| 502 Provider Error | 是 | 尝试其他 Provider |
| 503 Unavailable | 是 | 等待后重试 |
指数退避示例
async function withRetry<T>(
fn: () => Promise<T>,
maxRetries = 3,
baseDelay = 1000
): Promise<T> {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
if (i === maxRetries - 1) throw error;
if (error instanceof OpenAI.APIError) {
if (error.status === 429 || error.status >= 500) {
const delay = baseDelay * Math.pow(2, i);
await sleep(delay);
continue;
}
}
throw error;
}
}
throw new Error('Max retries exceeded');
}