mint/open-ai-server/error.md

错误处理指南

错误响应格式

API 错误响应（来自 OpenAI SDK）

{
  "error": "Error message",
  "type": "api_error",
  "code": "invalid_request_error",
  "param": "model",
  "details": {
    "status": 400,
    "headers": {},
    "request_id": "req_123",
    "response": {
      // 原始API响应
    }
  },
  "raw_error": {
    "name": "OpenAIError",
    "message": "Detailed error message",
    "stack": "Error stack trace (development only)"
  }
}

服务器内部错误响应

{
  "error": "Internal server error",
  "message": "Specific error message",
  "type": "NetworkError",
  "details": {
    "name": "NetworkError",
    "message": "Connection failed",
    "stack": "Error stack trace (development only)",
    "cause": null,
    "errno": -3008,
    "code": "ENOTFOUND",
    "syscall": "getaddrinfo",
    "hostname": "api.example.com"
  }
}

流式响应错误

{
  "error": "Streaming failed",
  "type": "streaming_error",
  "status": 429,
  "code": "rate_limit_exceeded",
  "details": {
    "name": "RateLimitError",
    "message": "Rate limit exceeded",
    "stack": "Error stack trace (development only)",
    "headers": {},
    "request_id": "req_456"
  }
}

常见错误类型

1. 认证错误 (401)

curl -X POST http://localhost:4000/api/openai \
  -H "Content-Type: application/json" \
  -d '{
    "open_ai_url": "https://generativelanguage.googleapis.com/v1beta/openai",
    "api_key": "invalid_key",
    "payload": {
      "model": "gemini-2.0-flash-exp",
      "messages": [{"role": "user", "content": "Hello"}]
    }
  }'

2. 无效模型错误 (400)

curl -X POST http://localhost:4000/api/openai \
  -H "Content-Type: application/json" \
  -d '{
    "open_ai_url": "https://generativelanguage.googleapis.com/v1beta/openai",
    "api_key": "valid_key",
    "payload": {
      "model": "invalid-model-name",
      "messages": [{"role": "user", "content": "Hello"}]
    }
  }'

3. 速率限制错误 (429)

当请求过于频繁时会返回速率限制错误。

4. 网络连接错误 (500)

当无法连接到 API 服务时返回网络错误。

调试技巧

1. 使用调试端点

curl -X POST http://localhost:4000/api/debug \
  -H "Content-Type: application/json" \
  -d '{
    "test": "debug request"
  }'

2. 设置开发环境

NODE_ENV=development PORT=4000 npm start

在开发环境下会显示完整的错误堆栈信息。

3. 检查服务器日志

所有错误都会在服务器端打印详细日志：

API Error: OpenAIError: Invalid API key provided
    at new OpenAIError (/path/to/error)
    ...

错误排查步骤

1. 检查 API 密钥：确保 API 密钥有效且有相应权限
2. 验证 URL：确保使用正确的 baseURL
3. 检查模型名称：确认模型名称正确且可用
4. 查看速率限制：检查是否超过 API 调用限制
5. 网络连接：确认能够访问目标 API 服务
6. 参数验证：检查请求参数格式是否正确

示例：完整错误响应

{
  "error": "The model `invalid-model` does not exist",
  "type": "invalid_request_error",
  "code": "model_not_found",
  "param": "model",
  "details": {
    "status": 404,
    "headers": {
      "content-type": "application/json",
      "x-request-id": "req_123abc"
    },
    "request_id": "req_123abc",
    "response": {
      "error": {
        "message": "The model `invalid-model` does not exist",
        "type": "invalid_request_error",
        "param": "model",
        "code": "model_not_found"
      }
    }
  },
  "raw_error": {
    "name": "NotFoundError",
    "message": "The model `invalid-model` does not exist"
  }
}