流量限制

流量限制是指应用或用户在指定时间段内可以发出的 API 调用次数。如果超过此上限，或超过 CPU 的承载范围或总次数上限，则系统可能会对应用或用户采取节流措施。遭到节流的用户或应用发出的 API 请求将失败。

所有 API 请求均受到流量限制。图谱 API 和 Instagram Basic Display API 请求会受到平台流量限制，而市场营销 API 和 Instagram 开放平台请求会受到商家用例 (BUC) 流量限制。

公共主页 API 请求受到平台流量限制或 BUC 流量限制，具体取决于请求中使用的口令；使用应用程序访问口令或用户访问口令发出的请求会受到平台流量限制，而使用系统用户访问口令或公共主页访问口令发出的请求会受到商家用例流量限制。

对某个端点发出的调用达到足够次数后，包含大多数 API 响应的标头内会列出实时流量限制使用情况统计数据。平台流量限制使用情况统计数据也会在应用面板中显示。达到流量限制后，应用发出的任何后续请求会失败，并且 API 将返回错误代码。直到经过足够长的时间，调用计数降至限制之下后，才会恢复正常。

如果平台流量限制和商家用例流量限制同时适用于某个请求，则系统将对其应用商家用例流量限制。

平台流量限制

系统会在单个应用程序或用户层级中追踪平台流量限制（具体取决于请求中使用的口令类型）。

应用程序

系统会根据应用的流量限制计算使用应用程序访问口令发出的图谱 API 请求次数。应用的调用次数是指该应用在连续一小时内可以发出的调用数量，计算方式如下：

“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 格式的字符串，用于说明当前应用程序流量限制的使用情况。

标头内容

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 时间和总时间。应用的调用次数是指该应用在连续一小时内可以发出的调用数量，计算方式如下：

如果应用拥有“广告管理标准访问级别”功能的标准访问级别：

如果应用拥有“广告管理标准访问级别”功能的高级访问级别：

“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 时间和总时间。应用的调用次数是指该应用在连续一小时内可以发出的调用数量，计算方式如下：

如果应用拥有“广告管理标准访问级别”功能的标准访问级别：

如果应用拥有“广告管理标准访问级别”功能的高级访问级别：

“Number of Active Ads”是指每个广告账户的广告数量。

流量限制也可能受到连续一小时内的总 CPU 时间和总墙上时钟时间的限制。详情请查看 HTTP X-Business-Use-Case 标头中的 total_cputime 和 total_time。

如果您收到流量限制错误，也可以查看 X-Business-Use-Case 标头中的 estimated_time_to_regain_access，了解预计屏蔽时间。

目录

目录批处理

您的应用发出的请求次数将根据应用在连续一小时内针对每个目录编号可发出调用的次数、总 CPU 时间和总时间等流量限制指标进行计算，计算方式如下：

“unique users”是过去 28 天内商家的有意向独立用户数（所有目录中）。查看您目录中商品的用户数量越多，分配的调用配额就越多。

目录管理

您的应用发出的请求次数将根据应用在连续一小时内针对每个目录编号可发出的调用次数进行计算，计算方式如下：

“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）：

如果应用拥有“广告管理标准访问级别”功能的标准访问级别：

对于广告管理标准访问功能为高级访问级别的应用：

“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 小时内可以发出的调用数量，其计算方式如下：

“Leads Generated”是指过去 90 天内每个公共主页为此广告账户生成的潜在客户数量。

Messenger 开放平台

公共主页

公共主页流量限制可能会运用平台流量限制逻辑或 BUC 流量限制逻辑，具体取决于所用口令的类型。使用公共主页访问口令或系统用户访问口令发出的任何公共主页 API 调用都将采用下述流量限制计算方法。使用应用程序访问口令或用户访问口令发出的任何调用都会受到应用程序流量限制或用户流量限制。

系统会根据您应用的调用次数计算该应用使用公共主页访问口令或系统用户访问口令向公共主页 API 发出的请求次数。应用的调用次数是指该应用在连续 24 小时内可以发出的调用数量，其计算方式如下：

“Number of Engaged Users”是指每 24 小时内与公共主页进行互动的用户的数量。

您的应用使用用户访问口令或应用访问口令向公共主页 API 发出的请求遵循平台流量限制逻辑。

为避免在使用公共主页公开访问内容功能时遭遇流量限制问题，建议您使用系统用户访问口令。

Spark AR 商品特效管理

系统会根据您应用的调用次数计算该应用向任何商品端点发出请求的次数。应用的调用次数是指该应用在连续一小时内可以发出的调用数量，计算方式如下：

“Number of Catalogs”指的是您的应用管理的所有电商账户中目录的总数。

Threads

WhatsApp Business 管理 API

标头

您应用返回的所有 API 响应受到使用 BUC 逻辑的流量限制，这些响应都包含一个带有 JSON 格式字符串的 X-Business-Use-Case-Usage（适用于 v3.3 及更低版本的广告 API 调用）HTTP 标头，该字符串用于说明当前应用程序流量限制使用情况。此标头在一个调用中可以返回多达 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 响应的性能。

我正在构建抓取工具，我还应该关注哪些问题？

如果您正在构建抓取数据的服务，请参阅 Facebook 抓取条款。