錯誤與調試

RouteAPI 會盡量返回統一的錯誤結構，幫助客戶端判斷錯誤來源和處理方式。

標準錯誤結構

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

常見狀態碼

狀態碼	類型	常見原因	建議處理
400	請求錯誤	參數格式錯誤、模型不支持參數	檢查請求體和模型能力
401	認證錯誤	Token 缺失、錯誤或已刪除	檢查 Authorization
402	餘額錯誤	用戶餘額不足或 Token 額度耗盡	充值或調整額度
404	路徑錯誤	Endpoint 不存在	檢查 URL
429	限流	用戶、Token 或系統限流	降低併發或調整限流
500	系統錯誤	RouteAPI 內部錯誤	查看服務日誌

排查順序

1. 確認請求 URL、Token 和模型 ID。
2. 確認 Token 所屬用戶餘額、額度和訪問權限。
3. 查看控制台使用日誌，確認請求是否進入 RouteAPI。
4. 如果是流式請求，確認客戶端是否正確處理 SSE。

服務側錯誤與本地錯誤

RouteAPI 是網關係統，錯誤可能來自三層：

層級	示例
客戶端	請求體 JSON 錯誤、Token 缺失
RouteAPI	餘額不足、無權限
模型服務	服務限流、服務不可用、模型下線

生產排障時建議同時記錄：

• 請求時間
• Token 或用戶 ID
• 模型 ID
• HTTP 狀態碼
• RouteAPI 返回的錯誤 code
• 控制台使用日誌中的錯誤信息