GPT-6 Astra API 錯誤：15 個常見問題及修復方法
診斷 GPT-6 Astra API 的 15 種常見故障，包括 400、401、403、404、409、422、429、500、503、超時、WebSocket 狀態、工具和串流。
｜ Source: Elser AI
讓 API 事故惡化的最快方式，就是對每個錯誤都進行重試。格式錯誤的結構化資料不會因為等待而自我修復，而餘額不足的信用額度也不會因為工作者多試十次就恢復。請根據 HTTP 狀態碼、SDK 類別、error.type，特別是 error.code 來診斷錯誤。
安全的錯誤處理器
try { return await client.responses.create({ model: "gpt-6-astra", 輸入 }); } catch (error) { if (error instanceof OpenAI.APIConnectionError) { // Network, proxy, TLS, DNS or firewall path. } else if (error instanceof OpenAI.RateLimitError) { // Inspect code and Retry-After before deciding to retry. } else if (error instanceof OpenAI.APIError) { console.error(error.status, error.message, error.code); } else { throw error; } }
記錄請求 ID、時間戳記與時區、模型、端點、狀態、代碼、重試次數，以及經過清理的酬載特徵。預設情況下，絕不記錄 API 金鑰或機密的提示內容。
## 1. 400 錯誤請求
酬載格式錯誤或不相容：欄位錯誤、缺少輸入、工具架構無效、組合不支援或內容編碼不當。請閱讀訊息，與目前的 Responses 參考文件比對，並加入合約測試。請勿重試未經變更的輸入。
## 2. 401 驗證錯誤
金鑰或權杖無效、已過期、已撤銷或傳送錯誤。請確認機密注入與專案環境。輪換已曝露的金鑰；除錯時切勿將其印出。
## 3. 401 不正確的組織或專案
有效的金鑰仍可能指向錯誤的範圍。請檢查專案設定及任何明確的組織/專案標頭。確保金鑰、資源與計費範圍一致。
## 4. 401 IP 未經授權
請求來源與設定的允許清單不符。請從已核准的出口IP發送，或透過授權管理更新允許清單。從相同來源重試無效。
## 5. 403 權限被拒絕或區域不受支援
呼叫者缺乏對資源、模型或區域的存取權限。請驗證專案角色、模型可用性、資源所有權及支援國家/地區規則。請勿在內部日誌中將權限問題偽裝成「找不到」。
## 6. 404 找不到
回應、對話、向量儲存、檔案或其他識別碼錯誤、已過期或無法存取。請確認確切的 ID 與專案。若為使用者端，請避免洩漏該使用者範圍以外的資源存在。
## 7. 409 衝突
另一個請求在同時變更了資源。請重新載入當前狀態，針對新版本重新套用預期的變更，並使用最佳化鎖定或冪等性。盲目立即重試可能會重複衝突。
## 8. 422 無法處理的實體
格式在語法上可接受，但服務無法處理。請驗證大小、編碼、檔案狀態及欄位組合。官方表格建議重試，但請先排除確定性原因。
## 9. 429 請求或令牌速率限制
控制流量並在出現 `Retry-After` 時遵守該指示。否則，使用帶抖動的有限指數退避策略。協調各工作節點的重試預算，避免造成驚群效應。減少冗餘呼叫與大量令牌突發。
## 10. 429 `slow_down`
這是斜坡速率信號：即使表面限制看似足夠，流量增長仍過快。請遵循 `Retry-After`，降低請求速率，再逐步增加。OpenAI 目前的指引提供一個經驗法則：達到每分鐘一百萬輸入令牌後，每 15 分鐘的增長不應超過 50%；實際觸發條件因模型與情況而異。
## 11. 429 額度、消費或使用限制
錯誤碼包括 `credit_balance_exhausted`（點數餘額耗盡）、`organization_spend_limit_exceeded`（組織支出上限超額）、`project_spend_limit_exceeded`（專案支出上限超額）以及 `organization_usage_limit_exceeded`（組織使用上限超額）。這些情況需要補充點數或調整上限。重試並不能恢復存取權限。請通知擁有者並快速失敗。
## 12. 500 內部伺服器錯誤
短暫等待後以有限預算重試，若持續失敗請檢查狀態頁面。擷取請求 ID 以尋求支援。對於變更狀態的工作流程，請在重播整個請求前先調解工具端的副作用。
## 13. 503 模型過載
文件記載的類型/代碼為 `service_unavailable_error` / `server_is_overloaded`。請遵循 `Retry-After`，若無則退避重試。請注意，目前 Python SDK 指引將 429 的 `RateLimitError` 與 503 的 `InternalServerError` 區分開來；若您過載邏輯先前假設所有容量問題皆為 429，請同時捕捉兩者。
## 14. 連線或逾時錯誤
`APIConnectionError` 可能表示網路、代理伺服器、TLS 憑證、DNS 或防火牆問題。`APITimeoutError` 表示已超過時限。請重試安全的讀取操作、檢查企業代理伺服器設定，並避免停用 TLS 驗證。對於寫入操作，請在重試前確認該操作是否已執行。
## 15. WebSocket 狀態與串流失敗
`previous_response_not_found` 表示無法解析參照的狀態；官方指引建議重新發送完整的輸入上下文，並將 `previous_response_id` 設為 `null`。`websocket_connection_limit_reached` 反映了 60 分鐘的連線限制；請開啟新連線並繼續。同時，應處理 `response.failed`、`response.incomplete` 以及傳輸層的 `error` 事件，而非假設 socket 關閉即代表完成。
## 重試矩陣
| 類別 | 重試不變？ | 正確操作 |
| 400/401/403/404 | 否 | 修正請求、身分、權限或 ID |
| 409 | 對帳後 | 重新載入版本並安全套用 |
| 422 | 有時 | 先檢查確定性原因 |
| 429 速率/減速 | 是，有限制 | 遵循 `Retry-After`；退避與抖動 |
| 429 計費/限制 | 否 | 增加額度或變更核准限制 |
| 500/503 | 是，有界 | 退避、狀態檢查、保留請求 ID |
| 連線/超時 | 視情況而定 | 重試讀取；協調寫入 |
重試次數與總計經過的重試時間。在廣泛事件發生時使用斷路器，並為需要操作員審查的工作設置死信路徑。重試應是可觀察的，而非隱藏在層層堆疊的 SDK 與應用程式迴圈中。
## 常見問題
### 我是否應該對每個 429 都進行重試？
不。速率和斜坡錯誤可在所需延遲後重試；信用、支出和使用限制錯誤則需要帳戶操作。
### 為何要記錄請求 ID？
它讓支援人員及您自己的遙測資料，能將特定API請求與故障關聯起來，同時無需暴露完整的酬載內容。
### 我可以重試超時的工具呼叫嗎？
只有在確定它是否造成副作用之後。使用冪等性金鑰和重試前讀取的一致性協調。
### 使用者應該看到什麼？
簡潔且可操作的訊息，並在適當情況下提供安全的重試選項。將堆疊追蹤、提供者代碼及敏感細節保留於受保護的診斷資訊中。
## 結論
可靠的 GPT-6 Astra 錯誤處理始於分類。修正確定性的 4xx 請求，區分速率壓力與計費限制，對暫時性的 5xx 失敗進行退避，調和不明確的寫入操作，並將串流建模為狀態機。採用有界限的重試策略，加上良好的請求層級遙測，能解決比無差別重試更多的問題。
