Felo API PlatformFelo API Platform

指南

錯誤、限流與重試

讀懂錯誤回應和限流回應標頭，安全重試並定位常見故障。

每個 Felo API 都會回傳 JSON 錯誤內容，包含穩定的錯誤碼與 request ID。先讀 HTTP 狀態，再讀 code，最後讀 message。

錯誤封裝

目前正式環境的回應以 HTTP 狀態作為 status：

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}
欄位含義
statusHTTP 狀態碼，並在內容中重複一次
code機器可讀的錯誤碼
message給人閱讀的說明
request_id此請求的不透明識別碼；聯絡支援時請附上

部分較舊的 endpoint 範例使用 status: "error" 與不同的 code 字串。請依 HTTP 狀態與 code 分支處理，不要依賴 message 的確切措辭。

常見錯誤碼

HTTPCode含義處理方式
400Endpoint 專屬驗證碼參數缺少或無效修正請求；不要原樣重試
401UNAUTHORIZEDAPI key 缺少、無效、過期或已撤銷送出 Authorization: Bearer $FELO_API_KEY；若已撤銷請輪替 key
402INSUFFICIENT_CREDITS服務額度不足到 Console Billing 儲值後重試
404Endpoint 專屬未知的模型、任務或路由檢查模型 ID 或任務 ID 與 endpoint 路徑
429RATE_LIMITED觸發限流等待 Retry-After 後重試
5xxCHAT_FAILED、*_FAILED、SERVICE_UNAVAILABLE上游或服務故障以退避方式重試；持續發生請聯絡支援

各 endpoint 參考文件會列出該 endpoint 專屬的錯誤碼。請從 Chat API 錯誤 或你要呼叫的 endpoint 參考開始。

Request ID

Felo 的錯誤內容包含 request_id。請連同 endpoint、HTTP 狀態、錯誤碼、模型 ID 與任務 ID 一起記錄。絕不要記錄完整的 API key。

Model API 也接受可選的 X-Request-Id 請求標頭。送出後，它會回顯在回應中以便診斷，讓你能把自己的日誌與請求對應起來。若未送出，請使用回傳的 request_id。

限流

/v2/chat 是唯一有公開強制限流的 Felo endpoint：

  • 每個 API key，1 分鐘視窗。
  • 每位使用者，1 分鐘視窗。
  • 每位使用者，1 小時視窗。

擁有有效付費 Felo 訂閱（含企業訂閱）的使用者不受限制，也不會收到 X-RateLimit-* 標頭。若無法驗證訂閱狀態，限制仍然適用。

標頭含義
X-RateLimit-Limit目前生效的最嚴格維度上限
X-RateLimit-Remaining三個維度中剩餘額度的最小值
X-RateLimit-Reset目前視窗重設的 Unix 時間戳（秒）
Retry-After遇到 429 時建議的延遲秒數

其他 /v2/** endpoints 目前沒有強制限流。Model API 請求仍可能受上游供應商限制，表現為 429。

不要寫死數值上限。請讀取每次回應的標頭。

重試策略

情況是否重試？
400、401、402、404否。先修正請求、key 或餘額。
429是，在 Retry-After 或 X-RateLimit-Reset 之後。
5xx、逾時、連線重置是，使用指數退避與 jitter。
串流連線在回應中途中斷只有在應用程式能容忍重複生成時才重試。

建議的重試迴圈：

  1. 只重試冪等或可安全重複的請求。
  2. 使用指數退避：從約 1 秒開始，每次加倍，上限 30 秒。
  3. 加入隨機 jitter，避免用戶端同步重試。
  4. 嘗試少數幾次後停止，並把錯誤往外拋。
  5. 遇到 429 時，遵循 Retry-After，不要用自己的排程。

除錯順序

  1. 檢查 key 是否存在且未被撤銷。
  2. 用同一個 key 呼叫 GET /api/v1/models 確認認證。
  3. 對目標 endpoint 送出最小的有效請求。
  4. 逐一加入串流、工具或大型輸入。
  5. 非同步工作請先檢查任務狀態，再重新提交。

相關