限速是應用程式或用戶在指定時間範圍內可以發出的 API 呼叫次數。若超過此限制,或是超過 CPU 時間或總時間限制,應用程式或用戶就可能會遭到限速。遭限速用戶或應用程式所發出的 API 要求會失敗。
所有 API 要求都會受到限速的影響。圖形 API 和 Instagram 基本顯示 API 要求應遵循平台限速,行銷 API 和 Instagram 圖形 API 要求則應遵循企業使用案例(BUC)限速。
粉絲專頁 API 要求應遵循平台或 BUC 限速(視要求中使用的權杖而定);使用應用程式或用戶存取權杖發出的要求應遵循平台限速,使用系統用戶或粉絲專頁存取權杖發出的要求則應遵循企業使用案例限速。
當系統向端點發出足夠的呼叫時,即時限速使用量統計資料會在標頭中說明,這些標頭包含在大多數 API 回應中。應用程式主控板也會顯示平台限速使用量統計資料。一旦達到限速,應用程式發出的任何後續要求都將失敗,API 也將傳回錯誤代碼,直到呼叫次數低於限制所經過的時間已足夠。
如果平台和企業使用案例限速兩者皆可套用至某要求,則將套用 BUC 限速。
根據要求中使用的權杖類型,在個別應用程式或用戶層級中追蹤平台限速。
使用應用程式存取權杖發出的圖形 API 要求,會根據應用程式的限速進行計數。應用程式的呼叫次數是在循環一小時期間內可發出的呼叫次數,計算方式如下:
Calls within one hour = 200 * Number of Users
用戶數取決於應用程式擁有的不重複每日活躍用戶人數。如果發生每日使用量緩慢的情況(例如,應用程式在週末有較高的活動量,但在工作日的活動量較低),將使用每週或每月活躍用戶來計算應用程式的用戶人數。無論實際的應用程式安裝數量有多少,相較於每日互動低的應用程式,每日互動高的應用程式具有較高的限速。
請注意,這不是針對用戶的限制,而是針對應用程式所發出呼叫的限制。只要應用程式的總呼叫次數不超過應用程式上限,任何單一用戶每小時可以使用應用程式發出超過 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 格式的字串,用於說明目前的應用程式限速使用量。
索引鍵 | 參數值說明 |
---|---|
| 整數,表示應用程式累積一小時期間所發出之呼叫的百分比。 |
| 整數,表示分配給查詢處理之 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 第 3.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 圖形 API 發出的呼叫,會根據應用程式的呼叫次數進行計數。應用程式的呼叫次數對每個應用程式和應用程式用戶配對來說都是唯一的,而且是應用程式累積 24 小時期間所發出的呼叫次數。計算方式如下:
Calls within 24 hours = 4800 * Number of Impressions
曝光次數是應用程式用戶 Instagram 帳號的任何內容在過去 24 小時內進入用戶螢幕的次數。
應用程式向 LeadGen API 發出的要求,會根據應用程式的呼叫次數進行計數。應用程式的呼叫次數是累積 24 小時期間可發出的呼叫次數,計算方式如下:
Calls within 24 hours = 4800 * Leads Generated
名單型廣告數量是過去 90 天內該廣告帳號的每個粉絲專頁產生的名單型廣告數量。
Messenger 開放平台限速功能取決於所用的 API,在某些情況下則取決於訊息內容。
應用程式發出要求的次數以應用程式連續 24 小時內能夠發出的呼叫次數為準,計算方式如下:
Calls within 24 hours = 200 * Number of Engaged Users
互動用戶人數是商家能透過 Messenger 傳送訊息的用戶對象人數。
應用程式發出要求的次數以每個 Instagram 專業帳號使用應用程式能夠發出的呼叫次數,以及所用的 API 為準。
對話 API
傳送 API
私訊回覆 API
根據使用的權杖類型,粉絲專頁限速可使用平台或 BUC 限速邏輯。使用粉絲專頁或系統用戶存取權杖進行的任何粉絲專頁 API 呼叫,都使用以下的限速計算。任何使用應用程式或用戶存取權杖進行的呼叫,都應遵循應用程式或用戶限速。
應用程式透過粉絲專頁存取權杖或系統用戶存取權杖向粉絲專頁 API 發出的要求,會根據應用程式的呼叫次數進行計數。應用程式的呼叫次數是累積 24 小時期間可發出的呼叫次數,計算方式如下:
Calls within 24 hours = 4800 * Number of Engaged Users
互動用戶人數是指每 24 小時與粉絲專頁互動的用戶人數。
應用程式透過用戶存取權杖或應用程式存取權杖向粉絲專頁 API 發出的要求,會遵循平台限速邏輯。
為避免使用粉絲專頁公開存取內容功能時遇到限速問題,建議使用系統用戶存取權杖。
應用程式向任何商務端點發出的要求,會根據應用程式的呼叫次數進行計數。應用程式的呼叫次數是在循環一小時期間內可發出的呼叫次數,計算方式如下:
Calls within one hour = 200 + 40 * Number of Catalogs
目錄數量是應用程式管理的所有商務帳號的目錄總數。
呼叫類型 | 端點 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
呼叫類型 | 端點 |
---|---|
|
|
|
|
|
|
|
|
受到限速的應用程式透過 BUC 邏輯發出的所有 API 回應,都會附加 X-Business-Use-Case-Usage
(用於第 3.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 也將回應錯誤代碼。
錯誤代碼 | BUC 限速類型 |
---|---|
| 廣告洞察報告 |
| 廣告管理 |
| 自訂廣告受眾 |
| |
| LeadGen |
| Messenger |
error code 32 | 透過用戶存取權杖進行的粉絲專頁呼叫 |
error code 80001 | 透過粉絲專頁或系統用戶存取權杖進行的粉絲專頁呼叫 |
| 第 3.3 版和舊版的廣告 API(不含廣告洞察報告) |
| WhatsApp Business Management 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 回應的效能。
如果您正在建立抓取資料的服務,請參閱資料抓取條款。