限速

限速是應用程式或用戶在指定時間範圍內可以發出的 API 呼叫次數。若超過此限制，或是超過 CPU 時間或總時間限制，應用程式或用戶就可能會遭到限速。遭限速用戶或應用程式所發出的 API 要求會失敗。

所有 API 要求都會受到限速的影響。圖形 API 和 Instagram 基本顯示 API 要求應遵循平台限速，行銷 API 和 Instagram 開放平台要求則應遵循企業使用案例（BUC）限速。

粉絲專頁 API 要求應遵循平台或 BUC 限速（視要求中使用的權杖而定）；使用應用程式或用戶存取權杖發出的要求應遵循平台限速，使用系統用戶或粉絲專頁存取權杖發出的要求則應遵循企業使用案例限速。

當系統向端點發出足夠的呼叫時，即時限速使用量統計資料會在標頭中說明，這些標頭包含在大多數 API 回應中。應用程式主控板也會顯示平台限速使用量統計資料。一旦達到限速，應用程式發出的任何後續要求都將失敗，API 也將傳回錯誤代碼，直到呼叫次數低於限制所經過的時間已足夠。

如果平台和企業使用案例限速兩者皆可套用至某要求，則將套用 BUC 限速。

平台限速

根據要求中使用的權杖類型，在個別應用程式或用戶層級中追蹤平台限速。

應用程式

使用應用程式存取權杖發出的圖形 API 要求，會根據應用程式的限速進行計數。應用程式的呼叫次數是在循環一小時期間內可發出的呼叫次數，計算方式如下：

用戶數取決於應用程式擁有的不重複每日活躍用戶人數。如果發生每日使用量緩慢的情況（例如，應用程式在週末有較高的活動量，但在工作日的活動量較低），將使用每週或每月活躍用戶來計算應用程式的用戶人數。無論實際的應用程式安裝數量有多少，相較於每日互動低的應用程式，每日互動高的應用程式具有較高的限速。

請注意，這不是針對用戶的限制，而是針對應用程式所發出呼叫的限制。只要應用程式的總呼叫次數不超過應用程式上限，任何單一用戶每小時可以使用應用程式發出超過 200 次呼叫。例如，如果應用程式擁有 100 名用戶，該應用程式每小時可以發出 20,000 次呼叫。不過，互動最頻繁的前十名用戶可以發出其中的 19,000 次呼叫。

用戶

透過用戶存取權杖發出的圖形 API 要求，會根據用戶的呼叫次數進行計數。用戶的呼叫次數是累積一小時期間可發出的呼叫用戶次數。由於隱私考量，我們不會顯示用戶的實際呼叫次數值。

請注意，用戶的呼叫次數可分佈在多個應用程式中。例如，用戶可透過 App1 發出 X 呼叫，透過 App2 發出 Y 呼叫。如果 X+Y 超過用戶的呼叫次數，該用戶將受到限速。這並不一定代表有任何應用程式發生問題，而可能是用戶正在使用多個應用程式或誤用 API。

標頭

端點若從應用程式接收足夠的要求，會在回應中附加 X-App-Usage 或 X-Ad-Account-Usage（用於第 3.3 版及舊版的廣告 API 呼叫）HTTP 標頭。標頭將包含 JSON 格式的字串，用於說明目前的應用程式限速使用量。

標頭內容

X-Ad-Account-Usage 標頭內容

總 CPU 時間

處理要求所需的 CPU 時間量。當 total_cputime 達到 100 時，呼叫可能會受到限速。

總時間

處理要求所需的時間長度。當 total_time 達到 100 時，呼叫可能會受到限速。

X-App-Usage 標頭值範例

x-app-usage: {
    "call_count": 28,         //Percentage of calls made 
    "total_time": 25,         //Percentage of total time
    "total_cputime": 25       //Percentage of total CPU time
}

X-Ad-Account-Usage 標頭值範例

x-ad-account-usage: {
    "acc_id_util_pct": 9.67,   //Percentage of calls made for this ad account.
    "reset_time_duration": 100,   //Time duration (in seconds) it takes to reset the current rate limit score.
    "ads_api_access_tier": 'standard_access'   //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
}

主控板

應用程式主控板顯示速率受限的應用程式用戶人數、應用程式目前的應用程式限速使用量百分比，並顯示過去 7 天的平均活動。在應用程式限速卡中，點擊「檢視詳細資訊」並將滑鼠移到圖表上方任一點，查看更多有關該特定時刻使用量的詳細資訊。因為使用量取決於呼叫量，此圖表可能不會顯示完整 7 天。呼叫量較高的應用程式將顯示較多天數。

錯誤代碼

當應用程式或用戶已達到限速時，該應用程式或用戶發出的要求將填入，API 將回應錯誤代碼。

限速錯誤代碼

回應範例

{
  "error": {
    "message": "(#32) Page request limit reached",
    "type": "OAuthException",
    "code": 32,
    "fbtrace_id": "Fz54k3GZrio"
  }
}

Facebook 穩定限速代碼

最佳作法

• 達到限制後，即停止進行 API 呼叫。若繼續進行呼叫會增加您的呼叫次數，如此將增加再次成功進行呼叫前的時間。
• 平均分配查詢以避免流量尖峰。
• 使用篩選條件限制資料回應大小，並避免發出要求重複資料的呼叫。
• 檢查 X-App-Usage HTTP 標頭，查看應用程式距離其限制有多近，以及已達到限制後何時可以繼續進行呼叫。
• 如果用戶受到限速，請確認不是應用程式所造成。減少用戶的呼叫次數，或隨時間更平均地分配用戶的呼叫次數。

企業使用案例限速

所有行銷 API 要求以及使用系統或粉絲專頁存取權杖發出的粉絲專頁 API 要求，都遵循企業使用案例（BUC）限速，並視您查詢的端點而定。

針對行銷 API，限速將套用至同一企業使用案例中的廣告帳號。例如，具有廣告管理企業使用案例的所有端點將在同一廣告帳號中分享總配額。如果某個端點發出大量 API 要求並導致限制，設定同一企業使用案例的其他端點也將收到限速錯誤。配額取決於應用程式的行銷 API 存取層級。一般存取權限行銷 API 層級的配額將多於開發存取權限行銷 API 層級。預設情況下，新應用程式應處於開發層級。如果您需要升級以獲得更多限制配額，請在應用程式審查中升級為廣告管理一般存取權限的進階存取權限。

廣告洞察報告

應用程式向廣告洞察報告 API 發出的要求，會根據應用程式的限速衡量指標（例如呼叫次數、總 CPU 時間和總時間）進行計數。應用程式的呼叫次數是在循環一小時期間內可發出的呼叫次數，計算方式如下：

若應用程式具有廣告管理一般存取功能的一般存取權限：

若應用程式具有廣告管理一般存取功能的進階存取權限：

上線中廣告數量是每個廣告帳號目前的刊登中廣告數量。用戶錯誤是呼叫 API 時收到的錯誤數量。若要提高限速，您可以申請廣告管理一般存取權限功能。

限速也可能受連續一小時期間內的總 CPU 時間和經過時間的影響。如需詳細資訊，請查看 HTTP X-Business-Use-Case 標頭 total_cputime 和 total_time。

如果您收到限速錯誤，可同時參考 X-Business-Use-Case 標頭中的 estimated_time_to_regain_access，瞭解估計的封鎖時間。

廣告管理

應用程式向廣告管理 API 發出的要求，會根據應用程式的限速衡量指標（例如呼叫次數、總 CPU 時間和總時間）進行計數。應用程式的呼叫次數是在循環一小時期間內可發出的呼叫次數，計算方式如下：

若應用程式具有廣告管理一般存取功能的一般存取權限：

若應用程式具有廣告管理一般存取功能的進階存取權限：

上線中廣告數量是每個廣告帳號的廣告數量。

限速也可能受連續一小時期間內的總 CPU 時間和經過時間的影響。如需詳細資訊，請查看 HTTP X-Business-Use-Case 標頭 total_cputime 和 total_time。

如果您收到限速錯誤，可同時參考 X-Business-Use-Case 標頭中的 estimated_time_to_regain_access，瞭解估計的封鎖時間。

目錄

目錄批次

應用程式發出要求的次數以應用程式針對每一目錄編號連續一小時內能夠發出的限速衡量指標（例如呼叫次數、總 CPU 時間和總時間）為準，計算方式如下：

不重複用戶是過去 28 天內有意願之商家（所有目錄中）的不重複用戶數量。看到目錄中產品的用戶越多，分配的呼叫配額就越多。

目錄管理

應用程式發出要求的次數以應用程式針對每一目錄編號連續一小時內能夠發出的呼叫次數為準，計算方式如下：

不重複用戶是過去 28 天內有意願之商家（所有目錄中）的不重複用戶數量。看到目錄中產品的用戶越多，分配的呼叫配額就越多。

此公式適用於各種目錄端點。

有關如何取得現有速率使用量的詳細資訊，請參閱標頭。

限速也可能受連續一小時期間內的總 CPU 時間和經過時間的影響。如需詳細資訊，請查看 HTTP X-Business-Use-Case 標頭 total_cputime 和 total_time。

如果您收到限速錯誤，可同時參考 X-Business-Use-Case 標頭中的 estimated_time_to_regain_access，瞭解估計的封鎖時間。

自訂廣告受眾

應用程式向自訂廣告受眾 API 發出的要求，會根據應用程式的限速衡量指標（例如呼叫次數、總 CPU 時間和總時間）進行計數。應用程式的呼叫次數是累積一小時可發出的呼叫次數（絕不會超過 700,000 次），計算方式如下：

若應用程式具有廣告管理一般存取功能的一般存取權限：

若應用程式具有廣告管理一般存取功能的進階存取權限：

上線中自訂廣告受眾數量是每個廣告帳號的上線中自訂廣告受眾數量。

限速也可能受連續一小時期間內的總 CPU 時間和經過時間的影響。如需詳細資訊，請查看 HTTP X-Business-Use-Case 標頭 total_cputime 和 total_time。

如果您收到限速錯誤，可同時參考 X-Business-Use-Case 標頭中的 estimated_time_to_regain_access，瞭解估計的封鎖時間。

Instagram 開放平台

LeadGen

應用程式向 LeadGen API 發出的要求，會根據應用程式的呼叫次數進行計數。應用程式的呼叫次數是累積 24 小時期間可發出的呼叫次數，計算方式如下：

名單型廣告數量是過去 90 天內該廣告帳號的每個粉絲專頁產生的名單型廣告數量。

Messenger 開放平台

粉絲專頁

根據使用的權杖類型，粉絲專頁限速可使用平台或 BUC 限速邏輯。使用粉絲專頁或系統用戶存取權杖進行的任何粉絲專頁 API 呼叫，都使用以下的限速計算。任何使用應用程式或用戶存取權杖進行的呼叫，都應遵循應用程式或用戶限速。

應用程式透過粉絲專頁存取權杖或系統用戶存取權杖向粉絲專頁 API 發出的要求，會根據應用程式的呼叫次數進行計數。應用程式的呼叫次數是累積 24 小時期間可發出的呼叫次數，計算方式如下：

互動用戶人數是指每 24 小時與粉絲專頁互動的用戶人數。

應用程式透過用戶存取權杖或應用程式存取權杖向粉絲專頁 API 發出的要求，會遵循平台限速邏輯。

為避免使用粉絲專頁公開存取內容功能時遇到限速問題，建議使用系統用戶存取權杖。

Spark AR 商務特效管理

應用程式向任何商務端點發出的要求，會根據應用程式的呼叫次數進行計數。應用程式的呼叫次數是在循環一小時期間內可發出的呼叫次數，計算方式如下：

目錄數量是應用程式管理的所有商務帳號的目錄總數。

Threads

WhatsApp Business Management API

頁首

受到限速的應用程式透過 BUC 邏輯發出的所有 API 回應，都會附加 X-Business-Use-Case-Usage（用於第 3.3 版及舊版的廣告 API 呼叫）HTTP 標頭，內含 JSON 格式的字串，用於說明目前的應用程式限速使用量。此標頭在一次呼叫中最多可傳回 32 個物件。

X-Business-Use-Case 使用量標頭內容

總 CPU 時間

處理要求所需的 CPU 時間量。當 total_cputime 達到 100 時，呼叫可能會受到限速。

總時間

處理要求所需的時間長度。當 total_time 達到 100 時，呼叫可能會受到限速。

廣告 API 存取層級

僅限 ads_insights 和 ads_management 類型。層級允許應用程式存取行銷 API。預設情況下，應用程式位於 development_access 層級，Standard_access 為啟用較低的限速。若要取得較高的限速並到達標準層級，您可以申請「廣告管理一般存取權限」功能的「進階存取權限」。

X-Business-Use-Case-Usage 標頭值範例

x-business-use-case-usage: {
    "{business-object-id}": [
        {
            "type": "{rate-limit-type}",           //Type of BUC rate limit logic being applied.
            "call_count": 100,                     //Percentage of calls made. 
            "total_cputime": 25,                   //Percentage of the total CPU time that has been used.
            "total_time": 25,                      //Percentage of the total time that has been used.   
            "estimated_time_to_regain_access": 19,  //Time in minutes to regain access.
            "ads_api_access_tier": "standard_access"  //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
        }
    ],      
    "66782684": [
        {
            "type": "ads_management",
            "call_count": 95,
            "total_cputime": 20,
            "total_time": 20,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access" 
        }
    ],
    "10153848260347724": [
        {
            "type": "ads_insights",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access"
        }
    ],
    "10153848260347724": [
        {
            "type": "pages",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0
        }
    ],
...
}

錯誤代碼

當應用程式達到企業使用案例限速，應用程式發出的後續要求都將失敗，API 也將回應錯誤代碼。

錯誤代碼訊息範例

{   
"error": {      
    "message": "(#80001) There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.",      
    "type": "OAuthException",      
    "code": 80001,      
    "fbtrace_id": "AmFGcW_3hwDB7qFbl_QdebZ"   
    }
}

最佳作法

• 達到限制後，即停止進行 API 呼叫。繼續進行呼叫會繼續增加您的呼叫計數，因此再次呼叫成功的時間也會增加。
• 檢查 X-Business-Use-Case-Usage HTTP 標頭，查看廣告帳號距離其限制有多近，以及何時可以繼續進行呼叫。
• 驗證錯誤代碼和 API 端點，以確認節流類型。
• 切換到其他廣告帳號，稍後再回到這個帳號。
• 相較於變更現有廣告，建立新廣告是更好的做法。
• 將查詢平均分佈在兩個時間間隔，避免在高峰傳送流量。
• 使用篩選條件限制資料回應大小，並避免發出要求重複資料的呼叫。

常見問題

哪些可以算是 API 呼叫？

所有呼叫都會計入限速的次數，不只是個別 API 要求而已。例如，您可以發出單次 API 要求且指定多個編號，但是每個編號都會計入為一次 API 呼叫。

下表說明此概念。

強烈建議您盡可能在一個 API 要求中指定多個編號，因為這可以提升 API 回應的效能。

我正在建立資料抓取程式，其他還有什麼我應該注意的事項嗎？

如果您正在建立抓取資料的服務，請參閱資料抓取條款。