錯誤處理 - OpenModex

錯誤回應格式

所有 API 錯誤都回傳一致的 JSON 格式：

{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "code": "error_code"
  }
}

錯誤類型

狀態碼	類型	觸發時機
`400`	`invalid_request_error`	缺少或無效的參數
`401`	`authentication_error`	無效或缺少 API 金鑰
`403`	`permission_error`	金鑰缺少權限
`404`	`not_found_error`	無效的端點或模型
`429`	`rate_limit_error`	請求過多
`500`	`server_error`	內部伺服器錯誤
`502`	`upstream_error`	供應商回傳錯誤
`503`	`service_unavailable`	暫時性中斷

SDK 錯誤處理

import OpenModex, { APIError } from '@openmodex/sdk';

try {
  const response = await client.chat.completions.create({...});
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.statusCode);     // 429
    console.log(err.message);        // "Rate limit exceeded"
    console.log(err.code);           // "rate_limit_exceeded"

    if (err.isRateLimited) {
      // Wait and retry
    } else if (err.isAuthError) {
      // Check API key
    } else if (err.isServerError) {
      // Retry with backoff
    }
  }
}

from openmodex import OpenModex, APIError

try:
    response = client.chat.completions.create(...)
except APIError as e:
    print(e.status_code)   # 429
    print(e.message)       # "Rate limit exceeded"

    if e.status_code == 429:
        # Wait and retry
        pass
    elif e.status_code == 401:
        # Check API key
        pass

自動重試

所有 SDK 都會自動以指數退避策略重試暫時性錯誤（429、500、502、503、504）：

const client = new OpenModex({
  apiKey: 'omx_sk_...',
  maxRetries: 3,    // default: 2
  timeout: 60_000,  // default: 30000ms
});

最佳實踐

始終捕捉錯誤 — 不要讓 API 故障導致您的應用程式崩潰
使用容錯備援 — 為關鍵路徑設定備援模型
記錄 request_id — 在錯誤報告中包含 response.openmodex.request_id 以便獲得支援
設定適當的逾時 — 複雜提示設定較長時間，簡單查詢設定較短時間
處理串流錯誤 — 串流可能在回應中途失敗；緩衝部分內容