流量限制是指应用或用户在指定时间段内可以发出的 API 调用次数。如果超过此上限,或超过 CPU 的承载范围或总次数上限,则系统可能会对应用或用户采取节流措施。遭到节流的用户或应用发出的 API 请求将失败。
所有 API 请求均受到流量限制。图谱 API 和 Instagram Basic Display API 请求会受到平台流量限制,而市场营销 API 和 Instagram 图谱 API 请求会受到商家用例 (BUC) 流量限制。
公共主页 API 请求受到平台流量限制或 BUC 流量限制,具体取决于请求中使用的口令;使用应用程序访问口令或用户访问口令发出的请求会受到平台流量限制,而使用系统用户访问口令或公共主页访问口令发出的请求会受到商家用例流量限制。
对某个端点发出的调用达到足够次数后,包含大多数 API 响应的标头内会列出实时流量限制使用情况统计数据。平台流量限制使用情况统计数据也会在应用面板中显示。达到流量限制后,应用发出的任何后续请求会失败,并且 API 将返回错误代码。直到经过足够长的时间,调用计数降至限制之下后,才会恢复正常。
如果平台流量限制和商家用例流量限制同时适用于某个请求,则系统将对其应用商家用例流量限制。
系统会在单个应用程序或用户层级中追踪平台流量限制(具体取决于请求中使用的口令类型)。
系统会根据应用的流量限制计算使用应用程序访问口令发出的图谱 API 请求次数。应用的调用次数是指该应用在连续一小时内可以发出的调用数量,计算方式如下:
Calls within one hour = 200 * Number of Users
“Number of Users”基于应用的日活跃独立用户数量。如果部分时段的日活跃用户数量较少(例如,您的应用周末的使用量较高,但是工作日的使用量较低),则系统会使用周活跃用户和月活跃用户来计算应用的用户数量。无论应用的实际安装量如何,每日使用率较高应用的流量限制都会高于每日使用率较低的应用。
请注意,这不是针对每位用户设置的限制,而是针对应用发出调用的限制。只要您应用发出的总调用次数不超过应用上限,则在使用您的应用时,任何一位用户每小时都可以发出超过 200 次调用。例如,如果您的应用有 100 位用户,则该应用每小时可以发出 20,000 次调用,但前 10 位最活跃的用户可能发出了其中 19,000 次调用。
系统会根据特定用户的调用次数计算使用用户访问口令发出的图谱 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
“Number of Active ads”是指每个广告账户当前投放的广告的数量。“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
“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)
“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)
“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
“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
“Number of Impressions”是指过去 24 小时内来自应用用户 Instagram 账户中的任何内容在某个用户的屏幕上显示的次数。
系统会根据您应用的调用次数计算该应用向潜客开发广告 API 发出的请求次数。应用的调用次数是指该应用在连续 24 小时内可以发出的调用数量,其计算方式如下:
Calls within 24 hours = 4800 * Leads Generated
“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
“Number of Engaged Users”是指每 24 小时内与公共主页进行互动的用户的数量。
您的应用使用用户访问口令或应用访问口令向公共主页 API 发出的请求遵循平台流量限制逻辑。
为避免在使用公共主页公开访问内容功能时遭遇流量限制问题,建议您使用系统用户访问口令。
系统会根据您应用的调用次数计算该应用向任何商品端点发出请求的次数。应用的调用次数是指该应用在连续一小时内可以发出的调用数量,计算方式如下:
Calls within one hour = 200 + 40 * Number of Catalogs
“Number of Catalogs”指的是您的应用管理的所有电商账户中目录的总数。
调用类型 | 端点 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
调用类型 | 端点 |
---|---|
|
|
|
|
|
|
|
|
您应用返回的所有 API 响应受到使用 BUC 逻辑的流量限制,这些响应都包含一个带有 JSON 格式字符串的 X-Business-Use-Case-Usage
(适用于 v3.3 及更低版本的广告 API 调用)HTTP 标头,该字符串用于说明当前应用程序流量限制使用情况。此标头在一个调用中可以返回多达 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 流量限制类型 |
---|---|
| 广告成效分析 |
| 广告管理 |
| 自定义受众 |
| |
| 潜客开发广告 |
| Messenger |
error code 32 | 使用用户访问口令发出的公共主页调用 |
error code 80001 | 使用公共主页访问口令或系统用户访问口令发出的公共主页调用 |
| v3.3 及更低版本的广告 API(广告成效分析 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 响应的性能。
如果您正在构建抓取数据的服务,请参阅 Facebook 抓取条款。