限速是指應用程式或用戶在指定時段內可以執行的 API 呼叫次數。如果超出此限制,或超出 CPU 或總時間限制,則應用程式或用戶可能會被限速。由受限速用戶或應用程式提出的 API 要求都會失敗。
所有 API 要求都需遵守限速規定。Graph API 和 Instagram 基本顯示 API 要求均須遵守平台限速規定,而推廣 API 和 Instagram Graph API 要求則須遵守商業使用範例(BUC)限速規定。
視乎要求中所使用的憑證,專頁 API 要求須遵守平台或商業使用範例的限速規定;使用應用程式或用戶存取憑證提出的要求均須遵守平台限速規定,而使用系統用戶或專頁存取憑證提出的要求則必須遵守商業使用範例的限速規定。
對某個端點發出的呼叫達到足夠次數後,包含在大多數 API 回應中的標題便會列出即時限速配額使用量統計資料。平台限速配額使用量統計資料也會顯示在應用程式管理中心。達到限速配額後,應用程式提出的任何後續要求都會失敗,而 API 亦會傳回錯誤代碼,直到呼叫次數經過足夠時間而降至限制以下。
如果平台限速配額和商業使用範例限速配額同時適用於某項要求,則系統會套用商業使用範例限速配額。
視乎要求中所使用的憑證類型,系統會在個別應用程式或用戶級別追蹤平台限速配額。
使用應用程式存取憑證提出的 Graph API 要求會計入該應用程式的限速配額。應用程式的呼叫次數是指其在連續一小時內可以發出多少次呼叫,其計算方式如下:
Calls within one hour = 200 * Number of Users
用戶人數是根據應用程式的不重複每日活躍用戶而得出。如果在某些單日用量較低(例如您的應用程式在週末的活動量高,而平日的活動量低),系統便會使用每週和每月活躍用戶來計算應用程式用戶人數。無論實際應用程式安裝次數有多少,每日互動次數高的應用程式都會比每日互動次數低的應用程式有較高的限速配額。
請注意,這不是針對每位用戶所設的限制,而是對應用程式所發出呼叫設下的限制。任何個別用戶每小時都可透過應用程式發出多於 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 格式字串,用於說明目前應用程式的限速配額使用量。
鍵 | 值的說明 |
---|---|
| 整數,表示您的應用程式在連續一小時內發出的呼叫百分比。 |
| 整數,表示為處理查詢所分配的 CPU 時間百分比。 |
| 整數,表示為處理查詢所分配的總時間百分比。 |
鍵 | 值的說明 |
---|---|
| 在達到限速額度之前,對此廣告帳戶執行的呼叫百分比。 |
| 將目前的限速額度重設為 0 所需的時間長度(以秒為單位)。 |
| 可以讓您的應用程式存取推廣 API 的級別。根據預設,應用程式的級別為 |
處理要求所需的 CPU 時間。當 total_cputime
達到 100 時,呼叫可能會被限速。
處理要求所需的時間長度。當 total_time
達到 100 時,呼叫可能會被限速。
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: { "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 亦會傳回包含錯誤代碼的回應。
錯誤代碼 | 說明 |
---|---|
| 表示要求中使用的憑證所屬應用程式已達到限速配額。 |
| 表示要求中使用的憑證所屬用戶已達到限速配額。 |
| 表示廣告 API v3.3 版或較舊版本要求中使用的憑證已達到限速配額。 |
| 表示專頁 API 要求中使用的憑證所屬用戶或應用程式已達到限速配額。 |
| 表示已達到自訂限速配額。為協助解決此問題,請參閱您正在呼叫之特定 API 的支援文件,以了解可能適用的自訂限速配額。 |
| 表示我們注意到您的應用程式 API 要求數量出現不一致行為。如果您近期作出任何會影響 API 要求數量的變更,便可能會遇到這個錯誤。 |
{ "error": { "message": "(#32) Page request limit reached", "type": "OAuthException", "code": 32, "fbtrace_id": "Fz54k3GZrio" } }
錯誤代碼 | 說明 |
---|---|
| 查詢是否被限速。值: |
| 第一限速因素
|
| 第二限速因素
|
X-App-Usage
HTTP 標題,從而了解您的應用程式尚餘多少限額,以及在達到限額時,您可以在多久後再次發出呼叫。使用系統或專頁存取憑證提出的所有推廣 API 要求和專頁 API 要求,均須遵守商業使用範例(BUC)限速規定,並且取決於您要查詢的端點。
在推廣 API 中,限速規定會套用於廣告帳戶的同一商業使用範例。例如,同一廣告帳戶中的總配額會由所有屬於廣告管理商業使用範例的端點所共用。如果端點發出大量 API 要求且導致限速,其他配置了相同商業使用範例的端點也會收到限速錯誤。配額多少取決於應用程式的推廣 API 存取權限級別。相比存取權限為開發級別的推廣 API,存取權限為一般級別的推廣 API 享有更多配額。新應用程式的存取權限預設為開發級別。如果需要透過升級獲得更多限速配額,請透過應用程式審查將廣告管理一般存取權限升級至進階存取權限。
應用程式向廣告洞察報告 API 發出的要求將計入應用程式的限速衡量數據,例如呼叫次數、總 CPU 時間及總時間。應用程式的呼叫次數是指其在連續一小時內可以發出多少次呼叫,其計算方式如下:
在廣告管理一般存取權限功能上擁有一般存取權限的應用程式:
Calls within one hour = 600 + 400 * Number of Active ads - 0.001 * User Errors
在廣告管理一般存取權限功能上擁有進階存取權限的應用程式:
Calls within one hour = 190000 + 400 * Number of Active ads - 0.001 * User Errors
活躍廣告數量是指每個廣告帳戶目前刊登多少則廣告。用戶錯誤是指呼叫 API 時接收到的錯誤數量。如要獲得更高的限速配額,您可以申請廣告管理一般存取權限功能。
限速多少亦視乎在連續一小時內的總 CPU 時間和總實時時間。詳情請查看 HTTP X-Business-Use-Case
標題 total_cputime
和 total_time
。
如果您收到限速錯誤,您亦可以參閱封鎖時間估計值 X-Business-Use-Case
標題中的 estimated_time_to_regain_access
。
應用程式向廣告管理 API 發出的要求將計入應用程式的限速衡量數據,例如呼叫次數、總 CPU 時間及總時間。應用程式的呼叫次數是指其在連續一小時內可以發出多少次呼叫,其計算方式如下:
在廣告管理一般存取權限功能上擁有一般存取權限的應用程式:
Calls within one hour = 300 + 40 * Number of Active ads
在廣告管理一般存取權限功能上擁有進階存取權限的應用程式:
Calls within one hour = 100000 + 40 * Number of Active ads
活躍廣告數量是指每個廣告帳戶的廣告數量。
限速多少亦視乎在連續一小時內的總 CPU 時間和總實時時間。詳情請查看 HTTP X-Business-Use-Case
標題 total_cputime
和 total_time
。
如果您收到限速錯誤,您亦可以參閱封鎖時間估計值 X-Business-Use-Case
標題中的 estimated_time_to_regain_access
。
應用程式發出的要求將計入限速衡量數據,例如應用程式就每個目錄編號可在連續一小時內發出的呼叫次數、總 CPU 時間及總時間,計算方式如下所示:
Calls within one hour = 200 + 200 * log2(unique users)
不重複用戶是指在過去 28 天內對企業(所有目錄)有意向的不重複用戶人數。看到您目錄商品的用戶越多,分配的呼叫配額就會越多。
呼叫類型 | 端點 |
---|---|
POST | /{catalog_id}/items_batch |
POST | /{catalog_id}/localized_items_batch |
POST | /{catalog_id}/batch |
您的應用程式發出的要求會計入應用程式對每個目錄編號在連續一小時內可發出的呼叫次數,計算方式如下所示:
Calls within one hour = 20,000 + 20,000 * log2(unique users)
不重複用戶是指在過去 28 天內對企業(所有目錄)有意向的不重複用戶人數。看到您目錄商品的用戶越多,分配的呼叫配額就會越多。
多個目錄端點都會套用此公式。
如要進一步了解如何取得目前的限速使用量,請參閱標題。
限速多少亦視乎在連續一小時內的總 CPU 時間和總實時時間。詳情請查看 HTTP X-Business-Use-Case
標題 total_cputime
和 total_time
。
如果您收到限速錯誤,您亦可以參閱封鎖時間估計值 X-Business-Use-Case
標題中的 estimated_time_to_regain_access
。
應用程式向自訂廣告受眾 API 發出的要求將計入應用程式的限速衡量數據,例如呼叫次數、總 CPU 時間及總時間。應用程式的呼叫次數是指應用程式在連續一小時內可發出的呼叫數量(不會超過 700,000),計算方法如下:
在廣告管理一般存取權限功能上擁有一般存取權限的應用程式:
Calls within one hour = 5000 + 40 * Number of Active Custom Audiences
在廣告管理一般存取權限功能上擁有進階存取權限的應用程式:
Calls within one hour = 190000 + 40 * Number of Active Custom Audiences
活躍自訂廣告受眾數量是指每個廣告帳戶有多少位活躍自訂廣告受眾。
限速多少亦視乎在連續一小時內的總 CPU 時間和總實時時間。詳情請查看 HTTP X-Business-Use-Case
標題 total_cputime
和 total_time
。
如果您收到限速錯誤,您亦可以參閱封鎖時間估計值 X-Business-Use-Case
標題中的 estimated_time_to_regain_access
。
對 Instagram Graph API 發出的呼叫會計入呼叫應用程式的呼叫次數。每對應用程式及應用程式用戶組合都有其專屬的應用程式呼叫次數,即應用程式在連續 24 小時內已發出多少次呼叫。計算方式如下:
Calls within 24 hours = 4800 * Number of Impressions
展示次數是指過去 24 小時內,應用程式用戶 Instagram 帳戶的任何內容在某位用戶的畫面上顯示了多少次。
應用程式對名單型廣告 API 提出的要求會計入有關應用程式的呼叫次數。應用程式的呼叫次數是指其在連續 24 小時內可以發出多少次呼叫,其計算方式如下:
Calls within 24 hours = 4800 * Leads Generated
產生的潛在顧客數量是指過去 90 天內,每個專頁為此廣告帳戶產生了多少位潛在顧客。
Messenger 平台的速率限制視乎所用 API 以及某些情況下的訊息內容而定。
您的應用程式發出的要求會計入應用程式在連續 24 小時內可發出的呼叫次數,計算方式如下所示:
24 小時內的呼叫次數 = 200 * 互動用戶人數
互動用戶人數是企業可透過 Messenger 傳送訊息的用戶人數。
您的應用程式發出的要求會計入應用程式按每個 Instagram 專業帳戶和所用 API 可發出的呼叫次數。
對話 API
傳送 API
私人回覆 API
視乎所用的憑證類型,專頁限速配額可能會採用平台或商業使用範例限速邏輯。所有使用專頁存取憑證或系統用戶存取憑證發出的專頁 API 呼叫,均採用下方的限速配額計算方式。所有使用應用程式存取憑證或用戶存取憑證發出的專頁 API 呼叫,都必須遵守應用程式或用戶限速配額。
應用程式使用專頁存取憑證或系統用戶存取憑證對專頁 API 提出的要求,會計入有關應用程式的呼叫次數。應用程式的呼叫次數是指其在連續 24 小時內可以發出多少次呼叫,其計算方式如下:
Calls within 24 hours = 4800 * Number of Engaged Users
互動用戶人數是指每 24 小時有多少位用戶與專頁互動。
應用程式根據平台限速邏輯,透過用戶存取憑證或應用程式存取憑證對專頁 API 提出的要求。
為免在使用專頁公開存取內容功能時遇到限速問題,我們建議使用系統用戶存取憑證。
應用程式對任何商務端點提出的要求會計入有關應用程式的呼叫次數。應用程式的呼叫次數是指其在連續一小時內可以發出多少次呼叫,其計算方式如下:
Calls within one hour = 200 + 40 * Number of Catalogs
目錄數量是指由您應用程式管理的所有商務帳戶中的總目錄數量。
呼叫類型 | 端點 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
呼叫類型 | 端點 |
---|---|
|
|
|
|
|
|
|
|
您應用程式發出且遵守商業使用範例邏輯限速的所有 API 回應,都包含 X-Business-Use-Case-Usage
(適用於 v3.3 版及較舊版本的廣告 API 呼叫)HTTP 標題,以及 JSON 格式字串,用於說明目前應用程式限速配額使用量。此標題在一次呼叫中可以傳回多達 32 項物件。
錯誤代碼 | 值的說明 |
---|---|
| 與發出 API 呼叫的憑證相關的企業編號。 |
| 整數,表示您的應用程式在連續一小時內發出所允許呼叫的百分比。 |
| 距離呼叫不再被限速的時間,以分鐘計。 |
| 整數,表示為處理查詢所分配的 CPU 時間百分比。 |
| 整數,表示為處理查詢所分配的總時間百分比。 |
| 套用的限速類型。此值可以是以下其中一項: |
| 僅限 |
處理要求所需的 CPU 時間。當 total_cputime 達到 100 時,呼叫可能會被限速。
處理要求所需的時間長度。當 total_time 達到 100 時,呼叫可能會被限速。
僅限 ads_insights
和 ads_management
類型。可以讓您的應用程式存取推廣 API 的級別。根據預設,應用程式的級別為 development_access
,而 Standard_access
可降低限速。如要提高限速限額並達到標準級別,您可以要求取得廣告管理一般存取權限功能的進階存取權限。
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 亦會傳回包含錯誤代碼的回應。
錯誤代碼 | 商業使用範例限速類型 |
---|---|
| 廣告洞察報告 |
| 廣告管理 |
| 自訂廣告受眾 |
| |
| 名單型廣告 |
| Messenger |
error code 32 | 透過用戶存取憑證發出的專頁呼叫 |
error code 80001 | 透過專頁或系統用戶存取憑證發出的專頁呼叫 |
| v3.3 版及較舊版本的廣告 API,廣告洞察報告除外 |
| WhatsApp Business 管理 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" } }
X-Business-Use-Case-Usage
HTTP 標題,從而了解您的廣告帳戶尚餘多少限額,以及您可以在多久後再次發出呼叫。所有會計入限速配額的呼叫,而不只是個別 API 要求。例如,您可以提出指定多個編號的單一 API 要求,但每個編號都會計算為一次 API 呼叫。
下表將解釋此概念。
要求範例 | API 呼叫次數 |
---|---|
GET https://graph.facebook.com/photos?ids=5
| 3 |
| 3 |
我們強烈建議儘可能在一項 API 要求中指定多個編號,從而提高 API 回應的成效。
如果您正在建立能夠抓取資料的服務,請參閱我們的抓取條款。