create

open-ai-server/error.md

@@ -0,0 +1,175 @@
+# 错误处理指南
+
+## 错误响应格式
+
+### API 错误响应（来自 OpenAI SDK）
+
+```json
+{
+  "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)"
+  }
+}
+```
+
+### 服务器内部错误响应
+
+```json
+{
+  "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"
+  }
+}
+```
+
+### 流式响应错误
+
+```json
+{
+  "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)
+
+```bash
+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)
+
+```bash
+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. 使用调试端点
+
+```bash
+curl -X POST http://localhost:4000/api/debug \
+  -H "Content-Type: application/json" \
+  -d '{
+    "test": "debug request"
+  }'
+```
+
+### 2. 设置开发环境
+
+```bash
+NODE_ENV=development PORT=4000 npm start
+```
+
+在开发环境下会显示完整的错误堆栈信息。
+
+### 3. 检查服务器日志
+
+所有错误都会在服务器端打印详细日志：
+
+```text
+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. **参数验证**：检查请求参数格式是否正确
+
+## 示例：完整错误响应
+
+```json
+{
+  "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"
+  }
+}
+```