錯誤與疑難排解
根據錯誤來源和 HTTP 狀態找出呼叫問題，並選擇安全的復原方式。
當 API 請求失敗時，先儲存 HTTP 狀態碼和經過去識別化的錯誤資訊，再判斷問題來自請求、認證、模型還是伺服器端。不要在沒有確認原因時持續重試同一個請求。
先保護憑證和客戶資料
疑難排解記錄中不要包含完整 API Key、Authorization 或 x-api-key Header、Cookie、密碼、完整 Prompt、客戶檔案或其他敏感資訊。
先判斷錯誤來自哪裡
| 錯誤來源 | 常見表現 | 建議動作 |
|---|---|---|
| 請求內容 | JSON 無效、缺少欄位、參數類型錯誤、檔案格式不符合要求 | 根據錯誤資訊修正請求，不要直接重試 |
| 認證與權限 | API Key 缺失、無效，或者目前 Key 無權存取目標模型 | 檢查 Base URL、對應協議的身分驗證 Header、Key 狀態和模型權限 |
| 模型與資源 | 模型 ID、任務 ID 或請求路徑不存在 | 從模型廣場重新複製 ID，並核對資源所屬帳戶 |
| 平台或上游 | 服務暫時不可用、處理逾時或上游回傳錯誤 | 儲存診斷資訊，在有限次數內重試；持續失敗時停止請求 |
| 非同步任務 | 提交成功後任務失敗、長時間處理中或結果不可用 | 先查詢原任務狀態，避免直接重複建立任務 |
同一次失敗可能同時包含多個線索。例如 404 既可能是端點寫錯，也可能是模型或任務不存在，應結合最終請求 URL 和錯誤本文判斷。
HTTP 狀態速查
| HTTP 狀態 | 常見含義 | 建議復原方式 |
|---|---|---|
400 | 請求格式、參數或輸入內容有誤 | 修正請求後重新傳送 |
401 | API Key 缺失、無效，或者身分驗證 Header 不符合介面要求 | 檢查對應協議的認證方式；必要時建立並替換新 Key |
403 | 目前帳戶、Key 或模型的使用範圍不滿足請求 | 檢查帳戶狀態、權杖限制和模型權限 |
404 | Base URL、端點、模型或任務不存在 | 核對最終 URL、模型 ID、任務 ID 和所屬帳戶 |
429 | 請求頻率、併發、額度或服務容量受到限制 | 停止高頻請求，根據實際錯誤資訊降低負載並稍後重試 |
500–599 | 平台、閘道或上游服務暫時無法完成請求 | 儲存診斷資訊，使用有限次數的退避重試 |
這些狀態只用於快速判斷方向。不同協議和上游回傳的程式錯誤碼可能不同，應結合 HTTP 狀態、實際錯誤本文和對應 API Reference 判斷原因。
建議疑難排解流程
記錄失敗現象
儲存請求時間和時區、Method、Path、模型 ID、HTTP 狀態，以及經過去識別化和長度限制的錯誤資訊。回應中存在 Request ID 時一並儲存。
核對位址和認證
使用 https://api.agtcloud.cn/v1 作為 Base URL，並確認最終 URL 沒有重複的 /v1/v1。OpenAI 相容介面通常使用 Authorization: Bearer your-api-key；其他協議應檢查對應 Reference 要求的身分驗證 Header。
核對模型和請求內容
確認模型 ID 來自目前帳戶可見的模型清單；再檢查 Content-Type、JSON、必填欄位、檔案類型和輸入大小。
判斷是否適合重試
400、401、403 和明確的資源不存在問題應先修復。臨時網路或 5xx 故障可以在有限次數內重試，並逐步增加等待時間。
準備去識別化資訊
如果問題持續存在，整理最小重現步驟和診斷資訊。不要為了疑難排解複製完整 Key、客戶 Prompt、文件或未去識別化回應。
安全地處理重試
- 普通只讀請求遇到臨時故障時，可以採用有限次數的退避重試。
- 參數、認證和權限問題只有在修復原因後才應再次傳送。
- 建立任務、呼叫外部工具或其他可能產生副作用的請求，在重新傳送前先確認原請求是否已經生效。
- 非同步請求應優先查詢原任務 ID，不要僅因為用戶端逾時就建立重複任務。
- 設定最大重試次數和總等待時間；持續失敗時停止自動請求並保留診斷資訊。
準備哪些疑難排解資訊
| 資訊 | 範例或說明 |
|---|---|
| 發生時間 | 包含日期、時間和時區 |
| 請求位置 | Method 和 Path，不包含完整 API Key |
| 呼叫目標 | 模型 ID；非同步任務可附任務 ID |
| 回應結果 | HTTP 狀態和去識別化錯誤資訊 |
| 請求特徵 | 是否串流、是否包含工具、是否為非同步任務 |
| 用戶端環境 | SDK 名稱與版本、執行時版本、最小重現步驟 |
| 追蹤資訊 | 回應中存在時儲存 Request ID |
需要查詢程式錯誤碼和處理建議時，請檢視錯誤碼參考。仍未解決時，可以繼續檢視 Request ID 和 FAQ。首次串接問題請重新核對快速開始和 API Key、Base URL 與認證。