你的程式代理說它新增了重試和速率限制處理，測試通過了。 在你相信那件事之前，先查查測試是針對什麼執行的。
在我們用 3 個程式代理執行的測試中（210 次執行），我們要求他們讓應用程式處理 API 失敗並證明它能正常運作。 在要求可運作程式碼的 140 次執行中，有 76% 是代理使用 fetch stubs、httpx.MockTransport 或一次性的 HTTP 伺服器，手動重現該失敗。 在 75 次真實 API 可用且提示未排除該選項的測試中，其中 0 次測試使用了該應用程式的真實 API URL。 像這樣通過的測試證明代理的程式碼能處理代理所想像的失敗。 這和 API 傳送的錯誤是不同的。
檢查清單
- 問問它是針對什麼進行測試的。 問代理程式：「你測試時應用程式呼叫了哪個網址？又是哪個回傳錯誤？」如果答案是它寫的存根或本地伺服器，就把測試當作它新增程式分支的單元測試。
- 找找為測試新增的切換選項。 搜尋差異中新的環境變數、基本 URL 設定或旗標。 在我們的測試中，在呼叫 GitHub、OpenAI 或天氣 API 的應用程式上進行的 105 次執行中，有 61 次新增了一個。 決定是否要在正式環境（生產環境）中使用它。
- 請將程式碼與 API 文件中的行為進行檢查。 每個 API 都有其獨特的失效方式：
-
GitHub：當你超過主要速率限制時，會得到 403 或 429，其中
x-ratelimit-remaining設為0，然後等待直到x-ratelimit-reset中的時間，以 UTC 紀元秒計。 對於次級速率限制，如果有的話，請等到retry-after；否則，如果x-ratelimit-remaining是0，則等到x-ratelimit-reset；否則，至少等待 1 分鐘。 只檢查429的程式碼會漏掉403。 -
OpenAI：有些 429 是關於 帳單和支出上限的，比如
credit_balance_exhausted。 重試也沒用。 每次遇到 429 都重試的程式碼會讓你看不到問題。 -
Anthropic：spend cap 429 沒有
retry-after標頭，overload 回傳 529，只知道標準狀態碼的程式碼可能不會預期這種情況。
-
GitHub：當你超過主要速率限制時，會得到 403 或 429，其中
- 請檢查其讀起來是否通順
Retry-After。 標頭包含秒數或 HTTP 日期（RFC 9110）。 請確認程式碼是否能處理 API 傳送的格式，限制嘗試次數和總等待時間，且不會在本身已具重試機制的 SDK 之上再額外重試。 - 檢查使用者在重試用盡時看到什麼。 尋找清晰訊息，而不是堆疊追蹤或無止盡的旋轉器，並檢查使用者不會遺失工作內容。
- 在真實網址上執行應用程式，並在模擬失敗情況下運行。 這是唯一能顯示執行中的應用程式、SDK 與重試政策如何協同運作的步驟。
如何驗證由代理程式撰寫的錯誤處理
| Approach | 你發現的 | 你錯過什麼 |
|---|---|---|
| 查看 diff | 程式碼是否看起來正確 | 它在面對 API 的真實回應時是否表現正確 |
| 執行代理程式的測試 | 它寫出的分支能夠執行 | 存根沒有建模的全部：真實狀態碼、標頭、錯誤主體和 SDK 重試 |
| 一直呼叫真正的 API，直到呼叫失敗為止 | 實際行為 | 你無法隨需觸發失敗，而且會消耗實際配額 |
| 在真實網址上執行應用程式，在模擬失敗的情況下 | 執行中的應用程式、SDK 以及重試政策如何處理 API 自身的錯誤 | 單獨來看，你的程式碼。 保留代理人的單元測試為此。 |
在你的應用程式上試試看
Dev Proxy 會攔截你的應用程式發送給真實 API 的請求，並回傳你選擇的錯誤，且應用程式的程式碼不會被更改。 對於熱門的 API，先從 預設開始。 為了查詢 GitHub 的速率限制處理，你的代理程式寫道：
devproxy config get github-rate-limiting
devproxy --config-file "~dataFolder/configs/github-rate-limiting/.devproxy/devproxyrc.json"
執行你的應用程式並觀察開發代理的輸出。 當你的應用程式超過限制時，預設會回傳帶有 GitHub 速率限制標頭的 429 回應。 預設裡的 RetryAfterPlugin 會告訴你，你的應用程式是否會在等待時間結束前再次呼叫 API。
openai-throttling和anthropic-throttling預設對服務提供者自己的速率限制錯誤也有同樣的處理，並且openai-throttling會回傳一個credit_balance_exhausted429，不應該重試。
對於其他 API：
- GenericRandomErrorPlugin 會以你選擇的速率回傳你定義的錯誤。 將速率設定為
--failure-rate。 請參考 使用隨機錯誤測試我的應用程式。 - LatencyPlugin 會延遲回應，讓你可以檢查代理設定的逾時時間。 請參見 模擬慢速 API 回應。
你也可以請你的程式代理幫忙寫 Dev Proxy 設定。把 Dev Proxy MCP 伺服器 加到你的代理程式，讓它能查閱 Dev Proxy 文件和最佳實務，並檢查你安裝的版本。 像審查代理寫的其他程式碼一樣，檢視那個設定。
要安裝 Dev Proxy，請參見 設定 Dev Proxy。
