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

哈囉，我是浪花科技的資深工程師 Eric。在開發 WordPress 專案時，我們很常需要跟各種第三方服務打交道，不管是金流、物流、行銷自動化還是天氣資訊，幾乎都離不開 API 串接。但你有沒有遇過這種情況：測試時好好的，一上線，使用者一多，API 就開始噴錯，甚至隔天收到服務商的警告信，說你的 API Key 因為請求過於頻繁被暫時停用了？

相信我，這絕對是每個工程師都經歷過的惡夢。想當年我還是個菜鳥時，也曾因為沒處理好 API Rate Limit，半夜被叫起來救火。今天，我就來跟大家聊聊這個看似不起眼，卻是決定你專案穩定性的關鍵——API Rate Limit 與重試機制。搞懂它，你就能寫出更強健、更優雅、更不容易「被鎖帳號」的程式碼。

為什麼 API 要有流量限制 (Rate Limit)？這不是找麻煩嗎？

在我們深入探討解法之前，得先搞懂「為什麼」。很多新手會覺得 API Rate Limit 是服務商故意刁難，但其實這是一個保護機制，對服務提供者和使用者雙方都有好處：

• 維持伺服器穩定性：想像一下，如果沒有任何限制，一個寫壞的迴圈或是一個惡意攻擊，就可能在瞬間發出數百萬個請求，直接把對方的伺服器打掛。這對所有使用者來說都是災難。
• 確保公平使用：API 資源是共享的。Rate Limit 確保沒有任何單一使用者可以佔用所有資源，讓大家都能穩定地使用服務。
• 安全性考量：限制請求頻率可以在一定程度上防範暴力破解（Brute-force）之類的攻擊。
• 商業模式：很多服務會根據你的 API 用量收費，Rate Limit 也是他們區分不同付費等級的方式之一。

當你超過了服務商設定的流量限制時，最常收到的 HTTP 狀態碼就是 429 Too Many Requests。有時候，如果伺服器真的不堪負荷，也可能會回傳 503 Service Unavailable。看到這些錯誤碼，不要慌，這不是世界末日，而是 API 在跟你溝通：「兄弟，你太快了，休息一下好嗎？」

第一道防線：事前預防，從源頭減少 API 請求

處理 Rate Limit 最好的方式，永遠是「預防勝於治療」。在你的 WordPress 程式碼裡瘋狂加上重試邏輯之前，先問問自己：這些 API 請求真的都是必要的嗎？

拜託，先好好讀 API 文件 (RTFM)！

這點我真的要囉嗦一下。太多工程師拿到 API Key 就直接開幹，完全不看文件。但魔鬼就藏在細節裡！你必須清楚知道：

• 每分鐘/每小時/每天的請求上限是多少？
• 這個限制是針對單一 IP，還是整個 API Key？
• 有沒有提供批次處理 (Batch) 的端點，可以一次送多筆資料，減少請求次數？
• API 的 Header 有沒有回傳目前的用量資訊？（例如 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset）

搞清楚這些規則，你才能從一開始就規劃好你的請求策略，而不是等到被擋了才來亡羊補牢。

用 WordPress Transients API 實現智慧快取

很多時候，我們請求的資料並不是即時變動的。例如，一個顯示「最新產品」的區塊，有必要每次使用者刷新頁面都去 call 一次產品 API 嗎？當然不用！

這時候，WordPress 內建的 Transients API 就是你的好朋友。它能讓你把資料暫存在資料庫（或如果你有設定 Redis/Memcached，會更快），並設定一個過期時間。在過期之前，直接從暫存取資料，完全不用 call API。

來看一段簡單的範例：

function get_awesome_products_from_api() {
    // 1. 先檢查有沒有快取資料
    $products = get_transient( 'awesome_products_cache' );

    // 2. 如果快取存在，直接回傳
    if ( false !== $products ) {
        return $products;
    }

    // 3. 快取不存在，才真的去 call API
    $response = wp_remote_get( 'https://api.example.com/products' );

    if ( is_wp_error( $response ) || 200 !== wp_remote_retrieve_response_code( $response ) ) {
        return []; // 請求失敗，回傳空陣列
    }

    $products = json_decode( wp_remote_retrieve_body( $response ), true );

    // 4. 將 API 結果存入快取，設定 1 小時 (3600 秒) 後過期
    set_transient( 'awesome_products_cache', $products, HOUR_IN_SECONDS );

    return $products;
}

你看，就這麼簡單幾行，可能就幫你的網站省下了 99% 的 API 請求，從源頭就避免了觸及 Rate Limit 的問題。

第二道防線：當錯誤發生時，如何優雅地重試

即便我們做了萬全準備，有時候還是會因為瞬間流量暴增而撞到 Rate Limit。這時候，一個好的重試機制就非常重要了。但「重試」可不是無腦地用 `while` 迴圈一直 try 就好，那樣只會讓情況更糟。

黃金策略：指數退避 (Exponential Backoff)

「指數退避」聽起來很學術，但概念很簡單：如果失敗了，就等一下再試；如果又失敗了，就等更久一點再試。

例如：第一次失敗後等 2 秒，第二次失敗後等 4 秒，第三次等 8 秒… 這種指數級增長的等待時間，給了對方伺服器喘息的空間，大大提高了下一次請求成功的機率。為了避免多個程序在完全相同的時間重試（Thundering Herd Problem），我們通常還會加上一個隨機的「抖動 (Jitter)」，讓等待時間多一點隨機性。

讓我們來實作一個帶有指數退避和 Jitter 的 API 請求函數：

function request_with_exponential_backoff( $url, $args, $max_retries = 5 ) {
    $attempt = 0;
    while ( $attempt < $max_retries ) {
        $response = wp_remote_post( $url, $args );

        if ( ! is_wp_error( $response ) ) {
            $http_code = wp_remote_retrieve_response_code( $response );

            // 請求成功 (2xx 狀態碼)
            if ( $http_code >= 200 && $http_code < 300 ) {
                return $response; // 成功，直接回傳結果
            }

            // 遇到 Rate Limit (429) 或伺服器忙碌 (503)，準備重試
            if ( in_array( $http_code, [ 429, 503 ] ) ) {
                $attempt++;
                if ( $attempt >= $max_retries ) {
                    // 已達最大重試次數，放棄
                    return new WP_Error( 'max_retries_exceeded', 'API request failed after ' . $max_retries . ' attempts.' );
                }

                // 檢查 API 有沒有回傳 Retry-After header
                $retry_after = wp_remote_retrieve_header( $response, 'retry-after' );
                if ( $retry_after ) {
                    $sleep_seconds = (int) $retry_after;
                } else {
                    // 計算指數退避時間 + Jitter (隨機毫秒)
                    $sleep_seconds = pow( 2, $attempt ) + ( mt_rand( 0, 1000 ) / 1000 );
                }

                sleep( $sleep_seconds );
                continue; // 進入下一次重試
            }
        }

        // 其他類型的錯誤，直接回傳
        return $response;
    }

    return new WP_Error( 'unknown_error', 'An unknown error occurred during the API request.' );
}

上面這段程式碼做了幾件很重要的事：

1. 設定了最大重試次數，避免無限重試下去。
2. 只針對 `429` 和 `503` 這類「暫時性」的錯誤進行重試。如果是 `404 Not Found` 或 `401 Unauthorized` 這種錯誤，重試再多次也沒用。
3. 優先遵從 API 回傳的 `Retry-After` Header，這是最精準的等待時間。
4. 如果沒有 `Retry-After`，才使用我們自己的「指數退避 + Jitter」策略。

終極武器：用 Queue 與 WP-Cron 實現非同步處理

對於那些不要求即時性，但又非常重要的 API 操作（例如：同步訂單到 ERP 系統），最好的方法是將它們「非同步化」。意思就是，不要在使用者當下的請求中直接去 call API，而是先把「待辦事項」丟進一個佇列 (Queue) 裡，然後讓 WordPress 的排程 (WP-Cron) 在背景慢慢消化這些工作。

這樣做的好處是：

• 使用者體驗超棒：使用者提交表單後立刻看到成功訊息，不用在原地乾等 API 回應。
• 可靠性極高：即使 API 當下掛了，工作仍在佇列中，WP-Cron 會在背景不斷地用我們上面寫的指數退避邏輯去重試，直到成功為止。
• 流量分散：所有 API 請求都被分散到不同的時間點執行，大大降低了觸及 Rate Limit 的風險。

在 WordPress 中，你可以使用像 Action Scheduler (WooCommerce 內建的函式庫) 這樣的工具來輕鬆實現 Queue 機制。這會讓你的應用程式架構提升到一個全新的水平。

工程師的老媽子囉嗦時間

總結一下，處理 API Rate Limit 與重試機制，絕對不是件小事。它考驗的是你對系統穩定性和使用者體驗的重視程度。記住以下幾個重點：

1. RTFM：永遠把 API 文件讀熟。
2. 快取優先：非必要的請求，用 Transients API 擋掉。
3. 優雅重試：不要無腦重試，善用指數退避 (Exponential Backoff) 策略。
4. 非同步化：對於重要但非即時的任務，導入 Queue 和 WP-Cron。
5. 做好日誌 (Logging)：API 請求成功或失敗，都應該留下紀錄，這樣出問題時你才知道去哪裡查。

把這些觀念內化到你的開發習慣裡，你會發現，你寫的 WordPress 網站不僅功能強大，而且穩定可靠，再也不用半夜被 API 錯誤的告警給嚇醒了。

---

延伸閱讀

• API 亂糟糟，專案火葬場？資深工程師的 WordPress REST API 設計聖經 (REST + JSON)
• 你的 WordPress 排程又失蹤了？資深工程師教你搞定 WP-Cron，從此告別「錯過排程」惡夢！
• 別讓你的網站等到天荒地老！WordPress Transients API 終極指南，一招榨乾網站潛在效能

如果你在 WordPress API 串接或系統架構上遇到了更複雜的挑戰，或是需要一個經驗豐富的團隊來幫你的專案把關，歡迎與浪花科技聯繫。我們很樂意提供專業的諮詢與開發服務，讓你的專案走得更穩、更遠。