故障排查

先從症狀開始，再依修正方式處理。多數失敗來自 base URL、key、模型 ID 或餘額。

症狀對照表

認證

已撤銷的 key 會回傳指名 key 前綴的訊息：

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key has been revoked (keyPrefix=...)"
}

檢查清單：

• Model API 與 Felo APIs 的標頭是 Authorization: Bearer <key>。
• Data API 也接受 X-API-Key: <key>。
• Key 沒有被引號包住，複製環境變數時也沒有殘留換行。
• 部署環境確實設定了該變數；本機可用的 key 可能在正式環境中不存在。
• Key 未被刪除或輪替。已刪除或輪替的 key 無法再次顯示；請建立新的。

建立 key 與相關限制請參閱認證。

Base URL 陷阱

兩個常見錯誤：

1. 在 SDK 已會延伸的 base URL 後面又加上 /chat/completions。
2. 把 Anthropic base URL 設成 https://openapi.felo.ai/api/v1。SDK 會接上 /v1/messages，請求就變成 /api/v1/v1/messages。

模型 ID 問題

模型 ID 是目錄中的公開 ID，不是上游供應商的內部名稱或顯示名稱。

• 在模型頁面或 GET /api/v1/models 查詢 ID。
• 確認模型支援你要呼叫的協議（supported_protocols）。
• 若你固定了通道，請確認該通道對這個模型已公布且可執行。不可用的通道不是 fallback。

請參閱通道與供應商路由。

串流問題

• 在請求內容中設定 stream: true，不要當成 query 參數。
• 以串流方式讀取回應內容。等待完整回應會讓串流失去意義。
• 部分代理與 serverless 平台會緩衝回應。請對代理該請求的路由關閉緩衝。
• Chat Completions 串流的是 choices[0].delta，不是 choices[0].message。最終內容會分散在許多 chunks 中送達。
• 連線中斷時，串流可能沒有乾淨的終止事件。請把斷線視為不完整的回應。

非同步任務問題

• 輪詢屬於該任務家族的狀態 endpoint。Felo 工作流程使用 GET /v2/tasks/{task_id}/status；模型的影片與圖像任務使用各自的生成 endpoint。
• 在每個終態停止，包括失敗與過期，不只是成功。
• 影片與圖像 callback 目前會被忽略。不要等待 webhook。
• 結果 URL 可能很短命。下載過期時，向狀態 endpoint 要求新的 URL。
• 重新提交前先檢查任務。對執行中的任務重新提交會產生重複任務，兩者都會計費。

請參閱非同步任務。

Data API 問題

• 保留 Data API 參考 中的確切 method 路徑。
• 請求內容依供應商而異。對某個供應商有效的欄位，不保證對另一個有效。
• 供應商錯誤可能出現在 4xx 回應中，並帶有供應商專屬訊息。請記錄 request_id 與回應內容。

安全提醒

• 絕不要把 API key 放進瀏覽器程式碼、行動 App 打包檔或公開儲存庫。請留在伺服器上並代理請求。
• 不要記錄完整 key。需要辨識時記錄前綴即可。
• 若懷疑 key 已外洩，請立即輪替。

聯絡支援前

請收集：

1. Endpoint 與 HTTP method。
2. HTTP 狀態、code 與 request_id。
3. 模型 ID 或任務 ID。
4. 含時區的時間戳。
5. 移除機密後的最小請求內容。

連同帳號 email 寄給支援。不要附上完整的 API key。

相關

• 錯誤、限流與重試
• 協議與 SDK
• 計費與額度
• 認證