API 中轉站可靠性檢查

這是一份可重複使用的操作範本，不是 Folkbench 對任何中轉站的實測結果。只有附上公開 run、時間、樣本和限制的發布快照，才構成 Folkbench 的評測事實。

目標

在串接新的 API 中轉站之前，先確認最小請求鏈路可用，並把失敗分成用戶端、協定、上游和伺服器端四類。驗收結果應該能讓另一位工程師用同樣的請求重新檢查。

事前準備

準備一份不含真實使用者資料的固定請求樣本。記錄模型 ID、請求主體、是否使用串流、逾時、重試次數和測試時間。測試憑證只放在本機的 secret manager 或臨時環境變數裡，不寫進日誌、螢幕截圖、程式碼儲存庫或公開頁面。

步驟一：固定請求與觀察邊界

先用最小請求，驗證 HTTP 狀態碼、回應標頭和回應主體是否符合服務商的文件。把請求 ID、模型 ID、狀態碼和總耗時記入測試表；不要把完整的 Authorization 標頭或原始回應直接貼進工單。

如果端點支援串流回傳，再另外執行一次串流請求。記錄第一個有效資料區塊抵達的時間、資料區塊之間是否持續送達、結束標記是否出現，以及連線關閉時用戶端能否得到明確結果。SSE 資料是事件串流，解析器應該依事件邊界處理，而不是依網路封包的切分去猜測 Token。

步驟二：失敗分類

用固定輸入分別觸發下列檢查：

1. 用戶端錯誤：無效模型、缺少參數或超出請求限制，應回傳可以定位問題的 4xx 結果。
2. 身分驗證錯誤：失效或權限不足的憑證應被明確拒絕，且回應中不能洩漏其他憑證或內部位址。
3. 上游錯誤：遇到上游逾時、速率限制或暫時無法使用時，應能區分可重試與不可重試。
4. 串流異常：連線中斷、缺少結束標記或只收到半個 JSON 事件，都應進入失敗路徑，而不是被當成成功產出的文字。

每類失敗至少保留狀態碼、錯誤類別、用戶端觀測時間，以及遮蔽敏感資訊後的簡短摘要。原始回應、trace 和螢幕截圖屬於過程證據，需依專案的私有物件儲存規則保存；它們不應出現在公開文章或排行榜中。

步驟三：設定重試邊界

只對具有明確冪等語意、或可以安全重複的請求自動重試。為重試設定總預算，並記錄第一次與最後一次請求的關聯 ID。遇到身分驗證失敗、參數錯誤或內容審核拒絕時，不要盲目重試。

一份清楚易讀的驗收表可以包含：

通過標準與清理

通過標準應在測試前寫好，例如「固定請求在三次獨立嘗試中都回傳完整結果，串流請求有明確的結束事件，身分驗證失敗不會被重試」。不要在看到結果之後才調整標準。

測試結束後撤銷臨時憑證，清除本機的原始回應，並保留一份只含摘要、時間和版本的驗收記錄。若要把結果發布到 Folkbench，必須先關聯真實的 run/attempt、證據 manifest 和發布快照；本文本身無法取代這些事實。