Initial commit

2025-11-30 08:25:17 +08:00
commit 07f3f3c71c
22 changed files with 5007 additions and 0 deletions
--- a/references/top-errors.md
+++ b/references/top-errors.md
@@ -0,0 +1,476 @@
+# Top 8 Errors with OpenAI Responses API
+
+**Last Updated**: 2025-10-25
+
+This document covers the most common errors encountered when using the Responses API and their solutions.
+
+---
+
+## 1. Session State Not Persisting
+
+**Error Symptom:**
+Model doesn't remember previous conversation turns.
+
+**Causes:**
+- Not using conversation IDs
+- Using different conversation IDs per turn
+- Creating new conversation for each request
+
+**Solution:**
+```typescript
+// ❌ BAD: New conversation each time
+const response1 = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'Question 1',
+});
+const response2 = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'Question 2', // Model doesn't remember question 1
+});
+
+// ✅ GOOD: Reuse conversation ID
+const conv = await openai.conversations.create();
+const response1 = await openai.responses.create({
+  model: 'gpt-5',
+  conversation: conv.id, // ✅ Same ID
+  input: 'Question 1',
+});
+const response2 = await openai.responses.create({
+  model: 'gpt-5',
+  conversation: conv.id, // ✅ Same ID - remembers previous
+  input: 'Question 2',
+});
+```
+
+**Prevention:**
+- Create conversation once
+- Store conversation ID (database, session, cookie)
+- Reuse ID for all related turns
+
+---
+
+## 2. MCP Server Connection Failed
+
+**Error:**
+```json
+{
+  "error": {
+    "type": "mcp_connection_error",
+    "message": "Failed to connect to MCP server"
+  }
+}
+```
+
+**Causes:**
+- Invalid server URL
+- Missing or expired authorization token
+- Server not responding
+- Network issues
+
+**Solutions:**
+```typescript
+// 1. Verify URL is correct
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'Test MCP',
+  tools: [
+    {
+      type: 'mcp',
+      server_label: 'stripe',
+      server_url: 'https://mcp.stripe.com', // ✅ Full HTTPS URL
+      authorization: process.env.STRIPE_OAUTH_TOKEN, // ✅ Valid token
+    },
+  ],
+});
+
+// 2. Test server URL manually
+const testResponse = await fetch('https://mcp.stripe.com');
+console.log(testResponse.status); // Should be 200
+
+// 3. Check token expiration
+const tokenExpiry = parseJWT(token).exp;
+if (Date.now() / 1000 > tokenExpiry) {
+  console.error('Token expired, refresh it');
+}
+```
+
+**Prevention:**
+- Use environment variables for secrets
+- Implement token refresh logic
+- Add retry with exponential backoff
+- Log connection attempts for debugging
+
+---
+
+## 3. Code Interpreter Timeout
+
+**Error:**
+```json
+{
+  "error": {
+    "type": "code_interpreter_timeout",
+    "message": "Code execution exceeded time limit"
+  }
+}
+```
+
+**Cause:**
+Code runs longer than 30 seconds (standard mode limit)
+
+**Solution:**
+```typescript
+// ❌ BAD: Long-running code in standard mode
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'Process this massive dataset',
+  tools: [{ type: 'code_interpreter' }], // Timeout after 30s
+});
+
+// ✅ GOOD: Use background mode for long tasks
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'Process this massive dataset',
+  background: true, // ✅ Up to 10 minutes
+  tools: [{ type: 'code_interpreter' }],
+});
+
+// Poll for results
+let result = await openai.responses.retrieve(response.id);
+while (result.status === 'in_progress') {
+  await new Promise(r => setTimeout(r, 5000));
+  result = await openai.responses.retrieve(response.id);
+}
+console.log(result.output_text);
+```
+
+**Prevention:**
+- Use `background: true` for tasks > 30 seconds
+- Break large tasks into smaller chunks
+- Optimize code for performance
+
+---
+
+## 4. Image Generation Rate Limit
+
+**Error:**
+```json
+{
+  "error": {
+    "type": "rate_limit_error",
+    "message": "DALL-E rate limit exceeded"
+  }
+}
+```
+
+**Cause:**
+Too many image generation requests in short time
+
+**Solution:**
+```typescript
+// Implement retry with exponential backoff
+async function generateImageWithRetry(prompt: string, retries = 3): Promise<any> {
+  for (let i = 0; i < retries; i++) {
+    try {
+      return await openai.responses.create({
+        model: 'gpt-5',
+        input: prompt,
+        tools: [{ type: 'image_generation' }],
+      });
+    } catch (error: any) {
+      if (error.type === 'rate_limit_error' && i < retries - 1) {
+        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
+        console.log(`Rate limited, retrying in ${delay}ms`);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      } else {
+        throw error;
+      }
+    }
+  }
+}
+
+const response = await generateImageWithRetry('Create an image of a sunset');
+```
+
+**Prevention:**
+- Implement rate limiting on your side
+- Use exponential backoff for retries
+- Queue image requests
+- Monitor API usage
+
+---
+
+## 5. File Search Relevance Issues
+
+**Problem:**
+File search returns irrelevant or low-quality results
+
+**Causes:**
+- Vague queries
+- Poor file quality (OCR errors, formatting)
+- Not enough context
+
+**Solutions:**
+```typescript
+// ❌ BAD: Vague query
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'Find pricing', // Too vague
+  tools: [{ type: 'file_search', file_ids: [fileId] }],
+});
+
+// ✅ GOOD: Specific query
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'Find the monthly subscription pricing for the premium plan in the 2025 pricing document',
+  tools: [{ type: 'file_search', file_ids: [fileId] }],
+});
+
+// ✅ ALSO GOOD: Filter low-confidence results
+response.output.forEach(item => {
+  if (item.type === 'file_search_call') {
+    const highConfidence = item.results.filter(r => r.score > 0.7);
+    console.log('High confidence results:', highConfidence);
+  }
+});
+```
+
+**Prevention:**
+- Use specific, detailed queries
+- Upload high-quality documents (PDFs, Markdown)
+- Filter results by confidence score (> 0.7)
+- Provide context in query
+
+---
+
+## 6. Variable Substitution Errors (Reusable Prompts)
+
+**Error:**
+Variables not replaced in prompt templates
+
+**Cause:**
+Incorrect variable syntax or missing values
+
+**Solution:**
+```typescript
+// ❌ BAD: Incorrect variable syntax
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'Hello {username}', // Not supported directly
+});
+
+// ✅ GOOD: Use template literals
+const username = 'Alice';
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: `Hello ${username}`, // ✅ JavaScript template literal
+});
+
+// ✅ ALSO GOOD: Build message dynamically
+function buildPrompt(vars: Record<string, string>) {
+  return `Hello ${vars.username}, your order ${vars.orderId} is ready.`;
+}
+
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: buildPrompt({ username: 'Alice', orderId: '12345' }),
+});
+```
+
+**Prevention:**
+- Use JavaScript template literals
+- Validate all variables before substitution
+- Provide defaults for optional variables
+
+---
+
+## 7. Chat Completions Migration Breaking Changes
+
+**Errors:**
+- `messages parameter not found`
+- `choices is undefined`
+- `system role not recognized`
+
+**Cause:**
+Using Chat Completions syntax with Responses API
+
+**Solution:**
+```typescript
+// ❌ BAD: Chat Completions syntax
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  messages: [{ role: 'system', content: 'You are helpful.' }], // Wrong
+});
+console.log(response.choices[0].message.content); // Wrong
+
+// ✅ GOOD: Responses syntax
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: [{ role: 'developer', content: 'You are helpful.' }], // ✅
+});
+console.log(response.output_text); // ✅
+```
+
+**Breaking Changes:**
+| Chat Completions | Responses API |
+|-----------------|---------------|
+| `messages` | `input` |
+| `system` role | `developer` role |
+| `choices[0].message.content` | `output_text` |
+| `/v1/chat/completions` | `/v1/responses` |
+
+**Prevention:**
+- Read migration guide: `references/migration-guide.md`
+- Update all references systematically
+- Test thoroughly after migration
+
+---
+
+## 8. Cost Tracking Confusion
+
+**Problem:**
+Billing different than expected
+
+**Cause:**
+Not accounting for tool tokens and conversation storage
+
+**Explanation:**
+- **Chat Completions**: input tokens + output tokens
+- **Responses API**: input tokens + output tokens + tool tokens + conversation storage
+
+**Solution:**
+```typescript
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'Hello',
+  store: false, // ✅ Disable storage if not needed
+  tools: [{ type: 'code_interpreter' }],
+});
+
+// Monitor usage
+console.log('Input tokens:', response.usage.prompt_tokens);
+console.log('Output tokens:', response.usage.completion_tokens);
+console.log('Tool tokens:', response.usage.tool_tokens);
+console.log('Total tokens:', response.usage.total_tokens);
+
+// Calculate cost
+const inputCost = response.usage.prompt_tokens * 0.00001; // Example rate
+const outputCost = response.usage.completion_tokens * 0.00003;
+const toolCost = response.usage.tool_tokens * 0.00002;
+const totalCost = inputCost + outputCost + toolCost;
+console.log('Estimated cost: $' + totalCost.toFixed(4));
+```
+
+**Prevention:**
+- Monitor `usage.tool_tokens` in responses
+- Set `store: false` for one-off requests
+- Track conversation count (storage costs)
+- Implement cost alerts
+
+---
+
+## Common Error Response Formats
+
+### Authentication Error
+```json
+{
+  "error": {
+    "type": "authentication_error",
+    "message": "Invalid API key"
+  }
+}
+```
+
+### Rate Limit Error
+```json
+{
+  "error": {
+    "type": "rate_limit_error",
+    "message": "Rate limit exceeded",
+    "retry_after": 5
+  }
+}
+```
+
+### Invalid Request Error
+```json
+{
+  "error": {
+    "type": "invalid_request_error",
+    "message": "Conversation conv_xyz not found"
+  }
+}
+```
+
+### Server Error
+```json
+{
+  "error": {
+    "type": "server_error",
+    "message": "Internal server error"
+  }
+}
+```
+
+---
+
+## General Error Handling Pattern
+
+```typescript
+async function handleResponsesAPI(input: string) {
+  try {
+    const response = await openai.responses.create({
+      model: 'gpt-5',
+      input,
+    });
+
+    return response.output_text;
+  } catch (error: any) {
+    // Handle specific errors
+    switch (error.type) {
+      case 'rate_limit_error':
+        console.error('Rate limited, retry after:', error.retry_after);
+        break;
+      case 'mcp_connection_error':
+        console.error('MCP server failed:', error.message);
+        break;
+      case 'code_interpreter_timeout':
+        console.error('Code execution timed out, use background mode');
+        break;
+      case 'authentication_error':
+        console.error('Invalid API key');
+        break;
+      default:
+        console.error('Unexpected error:', error.message);
+    }
+
+    throw error; // Re-throw or handle
+  }
+}
+```
+
+---
+
+## Prevention Checklist
+
+- [ ] Use conversation IDs for multi-turn interactions
+- [ ] Provide valid MCP server URLs and tokens
+- [ ] Use `background: true` for tasks > 30 seconds
+- [ ] Implement exponential backoff for rate limits
+- [ ] Use specific queries for file search
+- [ ] Use template literals for variable substitution
+- [ ] Update Chat Completions syntax to Responses syntax
+- [ ] Monitor `usage.tool_tokens` and conversation count
+
+---
+
+## Getting Help
+
+If you encounter an error not covered here:
+
+1. Check official docs: https://platform.openai.com/docs/api-reference/responses
+2. Search OpenAI Community: https://community.openai.com
+3. Contact OpenAI Support: https://help.openai.com
+
+---
+
+**Last Updated**: 2025-10-25