API 狂 Call 被鎖帳號？資深工程師教你 WordPress API 串接的優雅之道：Rate Limit 與重試機制全解析

嗨，我是 Eric，浪花科技的資深工程師。最近我在幫客戶優化一個串接 OpenAI 和 LINE 的自動化客服系統時，遇到了一個經典的「工程師車禍現場」。客戶很興奮地把系統推廣給幾千個會員，結果活動一上線，整個網站的 Log 充滿了紅色的錯誤訊息，API 回傳的不是智慧回覆，而是一堆冰冷的 429 Too Many Requests。

簡單來說，因為我們的請求太頻繁，被 API 供應商判定為惡意攻擊或超出配額，直接把我們「關進小黑屋」了。

這種情況在 API 經濟時代非常常見，無論你是串接金流、CRM (如 HubSpot)、還是 AI 模型，如果不處理 Rate Limit (速率限制)，你的應用程式就跟裸奔沒兩樣。今天這篇文章，我要來聊聊如何在 WordPress 中優雅地處理這個問題，特別是介紹指數退讓 (Exponential Backoff) 機制，讓你的程式碼學會「禮貌地等待」。

什麼是 API Rate Limit？為什麼 429 錯誤會毀了你的網站？

API Rate Limit 是服務供應商為了保護自己的伺服器不被單一用戶塞爆而設立的機制。它通常限制你在「特定時間單位內」只能發送「特定數量的請求」。

當你超過這個限制，伺服器就會回傳 HTTP 狀態碼 429 (Too Many Requests)。如果你沒有在程式碼中攔截這個錯誤並進行處理，使用者看到的可能就是：

• 網站卡住轉圈圈（因為 PHP 在癡癡地等）。
• 交易失敗或資料不同步。
• 最慘的情況：你的 API Key 被永久封鎖。

很多新手工程師的處理方式是：「失敗了？那就立刻再試一次！」這其實是大忌。如果對方已經覺得你太吵了，你還瘋狂敲門，只會被封鎖得更快。

拒絕暴力重試：認識「指數退讓」(Exponential Backoff)

要優雅地處理重試，業界標準做法是指數退讓 (Exponential Backoff)。這個聽起來很數學的名詞，原理其實很人性化：

「如果第一次敲門沒人應，等 1 秒再敲；還是沒人，等 2 秒；再沒人，等 4 秒…以此類推。」

這樣做的目的是讓系統有喘息的空間，而不是持續對已經過載的伺服器進行轟炸。

指數退讓的運作邏輯

1. 發送請求：第一次嘗試。
2. 失敗判斷：如果收到 429 或 5xx (伺服器錯誤)。
3. 計算等待時間：等待時間 = 基數 * (2 ^ 重試次數)。例如：1s, 2s, 4s, 8s。
4. 休眠 (Sleep)：程式暫停執行。
5. 重試：再次發送請求，直到成功或達到最大重試次數 (Max Retries)。

實戰：在 WordPress 中實作 API 重試機制

我們都知道 WordPress 內建了強大的 HTTP API (wp_remote_get, wp_remote_post)。下面我寫了一個封裝好的函式，你可以直接拿去放在你的外掛或 functions.php 裡使用。

這段程式碼包含了基本的指數退讓邏輯，並針對 WordPress 的經典編輯器與環境做了相容：

/**
 * 帶有指數退讓重試機制的 HTTP 請求函式
 *
 * @param string $url 請求的網址
 * @param array $args wp_remote_request 的參數
 * @param int $max_retries 最大重試次數
 * @return array|WP_Error 成功回傳回應陣列，失敗回傳 WP_Error
 */
function roamer_remote_request_with_retry( $url, $args = [], $max_retries = 3 ) {
    $attempt = 0;

    while ( $attempt <= $max_retries ) {
        // 發送請求
        $response = wp_remote_request( $url, $args );

        // 1. 檢查是否為 WordPress 內部錯誤 (連線失敗等)
        if ( is_wp_error( $response ) ) {
            // 如果是連線 timeout，通常值得重試
            // 這裡可以根據錯誤代碼決定是否重試
        } else {
            // 2. 獲取 HTTP 狀態碼
            $code = wp_remote_retrieve_response_code( $response );

            // 如果是 200-299，表示成功，直接回傳
            if ( $code >= 200 && $code < 300 ) {
                return $response;
            }

            // 如果不是 429 (Too Many Requests) 或 5xx (Server Error)，通常重試也沒用 (例如 404, 401)
            if ( $code !== 429 && $code < 500 ) {
                return $response;
            }
        }

        // 準備進行重試
        $attempt++;

        if ( $attempt > $max_retries ) {
            // 超過次數，跳出迴圈，回傳最後一次的結果
            break;
        }

        // 計算等待時間 (指數退讓：2 的次方)
        // mt_rand(0, 1000) / 1000 是為了加入一點 "Jitter" (隨機抖動)，避免多個請求同時重試造成 "Thundering Herd" 問題
        $sleep_seconds = pow( 2, $attempt ) + ( mt_rand( 0, 1000 ) / 1000 );
        
        // 記錄一下 Log (建議使用 WC_Logger 或 error_log)
        error_log( sprintf( "API 請求失敗 (嘗試 %d/%d). 等待 %.2f 秒後重試... URL: %s", $attempt, $max_retries, $sleep_seconds, $url ) );

        // 讓 PHP 睡一下
        // 注意：這會暫停整個 PHP 執行緒，請謹慎使用
        usleep( $sleep_seconds * 1000000 );
    }

    return $response;
}

程式碼解析：工程師的小囉嗦

• Jitter (隨機抖動)：我在計算等待時間時加了一點隨機數。這是為了防止「驚群效應」(Thundering Herd)。想像一下，如果 100 個請求同時失敗，然後大家都在準確的第 2 秒同時重試，伺服器大概會直接崩潰。加一點隨機性可以把請求錯開。
• 錯誤判斷：不是所有錯誤都要重試。如果 API 回傳 401 Unauthorized (你密碼打錯) 或 404 Not Found (網址打錯)，重試一萬次也不會成功，這時候直接回傳錯誤就好，別浪費時間。

進階思考：同步 vs 非同步 (Sync vs Async)

雖然上面的程式碼很好用，但我必須誠實告訴你一個風險：PHP 的執行時間限制 (Time Limit)。

如果您是在前台頁面 (User Request) 直接執行這段程式碼，使用 sleep() 或是 usleep() 會讓使用者感覺網站「卡住了」。如果重試時間加總超過了伺服器設定的 max_execution_time (通常是 30 秒或 60 秒)，使用者會看到 504 Gateway Timeout 錯誤。

更好的解決方案：背景處理

對於需要長時間重試的 API 請求 (例如同步大量訂單到 ERP)，最優雅的做法是將任務放入背景佇列 (Background Queue)。

1. WP-Cron：WordPress 內建的排程系統。雖然簡單，但依賴訪客流量觸發，時間不準。
2. Action Scheduler：這是 WooCommerce 內建的強大函式庫 (現在也可以單獨使用)。它支援重試、優先級、Log 記錄，是處理 API 重試的神器。

如果你的 API 請求非常關鍵，強烈建議使用 Action Scheduler 搭配非同步處理，這樣就算重試等待 10 分鐘，也不會影響前台使用者的體驗。

別忘了快取 (Cache) 才是最好的防禦

在研究怎麼「重試」之前，先想想能不能「不要請求」。

利用 WordPress 的 Transients API 把 API 回傳的結果快取起來。例如，如果你是抓取匯率資訊，不用每次有人載入頁面就 Call 一次 API，設定個 1 小時的快取，可以減少 99% 的 API 請求，自然就不會遇到 Rate Limit 了。

總結

API 串接看似簡單，魔鬼都在細節裡。Rate Limit 是每個資深工程師都會遇到的挑戰。透過實作指數退讓 (Exponential Backoff) 和隨機抖動 (Jitter)，你可以保護你的網站，也保護對方的伺服器，展現出身為開發者的專業素養。

如果你在串接複雜的第三方系統 (如 ERP、CRM、POS) 時遇到效能瓶頸，或者搞不定非同步的架構設計，歡迎隨時找我們聊聊！

想解決 API 串接的疑難雜症嗎？
立即聯繫浪花科技，打造穩定的系統架構

相關閱讀

• 資料不再是孤島！n8n Webhook + API 整合實戰藍圖，打造你的零時差自動化大腦
• 你的 WordPress 排程又失蹤了？資深工程師教你搞定 WP-Cron，從此告別「錯過排程」惡夢！
• WordPress 不再是孤島！資深工程師帶你串接 LINE / HubSpot / n8n，打造企業級自動化帝國