限速限制

限速是指應用程式或用戶在指定時段內可以執行的 API 呼叫次數。如果超出此限制，或超出 CPU 或總時間限制，則應用程式或用戶可能會被限速。由受限速用戶或應用程式提出的 API 要求都會失敗。

所有 API 要求都需遵守限速規定。Graph API 和 Instagram 基本顯示 API 要求均須遵守平台限速規定，而推廣 API 和 Instagram Graph API 要求則須遵守商業使用範例（BUC）限速規定。

視乎要求中所使用的憑證，專頁 API 要求須遵守平台或商業使用範例的限速規定；使用應用程式或用戶存取憑證提出的要求均須遵守平台限速規定，而使用系統用戶或專頁存取憑證提出的要求則必須遵守商業使用範例的限速規定。

對某個端點發出的呼叫達到足夠次數後，包含在大多數 API 回應中的標題便會列出即時限速配額使用量統計資料。平台限速配額使用量統計資料也會顯示在應用程式管理中心。達到限速配額後，應用程式提出的任何後續要求都會失敗，而 API 亦會傳回錯誤代碼，直到呼叫次數經過足夠時間而降至限制以下。

如果平台限速配額和商業使用範例限速配額同時適用於某項要求，則系統會套用商業使用範例限速配額。

平台限速

視乎要求中所使用的憑證類型，系統會在個別應用程式或用戶級別追蹤平台限速配額。

應用程式

使用應用程式存取憑證提出的 Graph API 要求會計入該應用程式的限速配額。應用程式的呼叫次數是指其在連續一小時內可以發出多少次呼叫，其計算方式如下：

用戶人數是根據應用程式的不重複每日活躍用戶而得出。如果在某些單日用量較低（例如您的應用程式在週末的活動量高，而平日的活動量低），系統便會使用每週和每月活躍用戶來計算應用程式用戶人數。無論實際應用程式安裝次數有多少，每日互動次數高的應用程式都會比每日互動次數低的應用程式有較高的限速配額。

請注意，這不是針對每位用戶所設的限制，而是對應用程式所發出呼叫設下的限制。任何個別用戶每小時都可透過應用程式發出多於 200 次呼叫，前提是應用程式的總呼叫數量未超出其上限。舉例來說，如果應用程式有 100 位用戶，則每小時可以發出 20,000 次呼叫。不過，您頭 10 位最活躍的用戶可以發出其中 19,000 次呼叫。

用戶

使用用戶存取憑證提出的 Graph API 要求會計入該用戶的呼叫次數。用戶的呼叫次數是指用戶在連續一小時內可以發出多少次呼叫。為了保障私隱，我們不會透露用戶實際呼叫次數的數值。

請注意，用戶的呼叫次數可以分散於多個應用程式。例如，某位用戶可以透過應用程式 1 發出 X 次呼叫，並透過應用程式 2 發出 Y 次呼叫。如果 X+Y 超出了用戶的呼叫次數，則該用戶會被限速。這並不一定表示任何應用程式做錯了什麼；這可能是用戶正在使用多個應用程式，或者濫用 API。

標題

端點從您應用程式接收到足夠要求後，便會在其回應中加入 X-App-Usage 或 X-Ad-Account-Usage（適用於 v3.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 Graph API

對 Instagram Graph API 發出的呼叫會計入呼叫應用程式的呼叫次數。每對應用程式及應用程式用戶組合都有其專屬的應用程式呼叫次數，即應用程式在連續 24 小時內已發出多少次呼叫。計算方式如下：

展示次數是指過去 24 小時內，應用程式用戶 Instagram 帳戶的任何內容在某位用戶的畫面上顯示了多少次。

注意事項

• Instagram 基本顯示 API 採用平台限速配額。
• 企業需求探索和主題標籤搜尋須受平台限速配額約束。

名單型廣告

應用程式對名單型廣告 API 提出的要求會計入有關應用程式的呼叫次數。應用程式的呼叫次數是指其在連續 24 小時內可以發出多少次呼叫，其計算方式如下：

產生的潛在顧客數量是指過去 90 天內，每個專頁為此廣告帳戶產生了多少位潛在顧客。

Messenger 平台

專頁

視乎所用的憑證類型，專頁限速配額可能會採用平台或商業使用範例限速邏輯。所有使用專頁存取憑證或系統用戶存取憑證發出的專頁 API 呼叫，均採用下方的限速配額計算方式。所有使用應用程式存取憑證或用戶存取憑證發出的專頁 API 呼叫，都必須遵守應用程式或用戶限速配額。

應用程式使用專頁存取憑證或系統用戶存取憑證對專頁 API 提出的要求，會計入有關應用程式的呼叫次數。應用程式的呼叫次數是指其在連續 24 小時內可以發出多少次呼叫，其計算方式如下：

互動用戶人數是指每 24 小時有多少位用戶與專頁互動。

應用程式根據平台限速邏輯，透過用戶存取憑證或應用程式存取憑證對專頁 API 提出的要求。

為免在使用專頁公開存取內容功能時遇到限速問題，我們建議使用系統用戶存取憑證。

Spark AR 商務特效管理

應用程式對任何商務端點提出的要求會計入有關應用程式的呼叫次數。應用程式的呼叫次數是指其在連續一小時內可以發出多少次呼叫，其計算方式如下：

目錄數量是指由您應用程式管理的所有商務帳戶中的總目錄數量。

WhatsApp Business 管理 API

標題

您應用程式發出且遵守商業使用範例邏輯限速的所有 API 回應，都包含 X-Business-Use-Case-Usage（適用於 v3.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 回應的成效。

我正在建立抓取工具，還需要注意哪些問題？

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