Questo documento è stato aggiornato.
La traduzione in Italiano non è ancora completa.
Aggiornamento inglese: 12 lug
Aggiornamento Italiano: 3 lug

Rate Limiting on the Graph API

Rate limiting defines limits on how many API calls can be made within a specified time period. Rate limits are imposed on every app.

Apps that excessively or persistently exceed their rate limits may be disabled.

Rate limiting in the Facebook Graph API should be encountered only in rare circumstances. This document describes what those limits are and how to handle them.

There are two major types of rate limits that can be encountered by your app: application-level rate limiting and page-level rate limiting.

Application-Level Rate Limiting

These limits apply to calls made using any access token other than a page access token.

All API calls from an app made after a rate limit is exceeded are throttled and will fail with error code = 4, CodedException. Calls will start to succeed again when the usage over the past hour falls back below the limit. Limits are calculated on a rolling one-hour window, and current utilization percentages can be seen on your app dashboard.

Rate limit dashboard

The rate limiting tool gives you information about how close your app is to being throttled. You can view information about the rate limits affecting your apps using two graphs in the app dashboard.

  • One graph shows the current utilization affecting your returned Graph API responses. This is a visual representation of the header value returned in Graph API requests.
Graph for an App Approaching Its Rate Limit
  • The second graph shows historical rate limits. You can choose to display data for the past 24 hours or the past 7 days. You can click on any sample in the historical graph to see more details about the utilization, including a per-method breakdown. Not all apps have historical data, because the presence of historical data depends on call volume. Apps with a higher volume of calls are more likely to have historical data available.
Historical Graph for App Exceeding Rate Limits in Past 24 Hours

Limits

The total number of calls your app can make per hour is 200 times the number of users. This isn't a per-user limit; any individual user can make more than 200 calls per hour, as long as the total for all users does not exceed the app maximum. For example, if your app has 100 users, the app can make 20,000 calls per hour. But your top ten most engaged users could make 19,000 of those calls.

When your app is rate limited, all calls for the app are limited, not just calls for a specific user.

The number of users for your app is calculated using the number of daily active users and today's new logins. In cases where there are slow periods of daily usage, the weekly active or even monthly active users are used to calculate the number of users for your app. Apps with high daily engagement will have higher rate limits than apps with low daily engagement, regardless of the actual number of app installs.

Caveats:

  • Not all API calls are subject to rate limits, so the number of calls you make may not match what you see in the rate limit tool.
  • We also throttle calls based on CPU time used and total time. Endpoints that require a lot of processing may cause your app to hit these limits, despite being below the call-volume limit. Apps rarely hit CPU time and total time limits, except for specialized endpoints. Information about endpoints that are using a lot of CPU time or total time can be seen in the historical graph, if available.
  • The Ads Insights API and the Marketing API may use a different set of rate limits. Please see the Marketing API Rate Limiting document at https://developers.facebook.com/docs/marketing-api/api-rate-limiting for more information on the Marketing API.

Recommendations

To avoid rate limiting:

  • Spread out queries evenly between two time intervals to avoid sending traffic in spikes.
  • Use filters to limit the data response size and avoiding calls that request overlapping data.
  • Use the rate limiting header to dynamically balance your call volume.

Rate limiting header

All responses to calls made to the Graph API include an X-App-Usage HTTP header. This header contains the current percentage of usage for your app. This percentage is equal to the usage shown to you in the rate limiting graphs. Use this number to dynamically balance your call load to avoid being throttled.

The rate limiting header is a JSON-formatted string in the following form:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

The values for x, y and z are whole numbers representing the percentage used values for each of the metrics. When any of these metrics exceed 100 the app will be rate limited.

Page-Level Rate Limiting

These limits apply to calls made using a page access token. Your app will receive error code 32 if you hit these limits.

The blog post at https://developers.facebook.com/blog/post/2016/06/16/page-level-rate-limits/ provides a detailed explanation of page level rate limiting.

Rate limit dashboard

For each page whose access token is used by your app to make calls, you can view the rate limiting charts for that page.

Limits

Rate limits are imposed on each page rather than the app. The rate limiting tool will give you information about how many apps use that page's access token and how close the page is to being throttled. Click on any sample to get more detail on the types of utilization.

The number of daily engaged people using a page is the unique number of people who have interacted with the page in a 24-hour period. An interaction with a page consists of a click on the page or page content.

The number of engaged users in the previous 24 hours is used to calculate the rate limits for the current 24-hour window.

A total of 4800 calls per daily engaged users can be made on behalf of the page per 24 hours in aggregate. As an example, if the page has 100 daily engaged users, then 480,000 calls can be made on behalf of the page in a 24-hour period. This 24-hour period is a sliding window that is updated every few minutes. The call limit is a per-page limit, so one app could make 400,000 calls and another could make 80,000. If a page is rate limited, only the calls from your app using that page's access token will be limited. This means that your app can still function normally for other calls.

The number of calls to your page is calculated as the estimated number of calls using your page access token per day. Pages with a larger number of calls per day may have more accurate rate limiting than pages with a smaller number of calls per day. Pages with a very small number of calls per day may have rate limit issues.

Caveats:

  • Not all API calls are subject to rate limits so the number of calls you make may not match what you see in the rate limit tool.
  • Facebook also throttles calls based on CPU time used and total time. Click on the graph in the rate limit tool on your dashboard for details.
  • The Ads Insights API and the Marketing API may use a different set of rate limits. Please see the Marketing API Rate Limiting document for more information on the Marketing API.

Recommendations

Once a page is throttled, the caller will get an error for subsequent calls with error code = 32, CodedException. It can take up to an hour for your requests to that page to be accepted again.

To avoid rate limiting:

  • Spread out queries evenly between two time intervals to avoid sending traffic in spikes.
  • Use filters to limit the data response size and avoiding calls that request overlapping data.
  • Use the rate limiting header to dynamically balance your call volume.

Rate limiting header

If enough calls are being made on behalf of a page to be considered for rate limiting by our system, we return an X-Page-Usage HTTP header. This header contains the current percentage of usage for the page. If you make calls using the access token of a page, you will get the X-Page-Usage value for that page only. This percentage is equal to the usage shown on the rate limiting graph for that page. Use this number to dynamically balance your call load to avoid being throttled.

The rate limiting header is a JSON-formatted string in the following form:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

The values for x, y and z are whole numbers representing the percentage used values for each of the metrics. When any of these metrics exceed 100 the app will be rate limited.

Account-Level Rate Limiting

These limits apply to calls made using user access tokens. Your app will receive error code 17 if this limit is reached. This happens when a specific user account is making too many calls to the API.

Note:

This can include user calls made over many apps and not just yours.

When a user is rate limited, API calls from the user are throttled.

To avoid rate limiting:

There's nothing you can do to prevent this. The user is making too many calls (possibly through other apps) and hence getting rate limited. However, if this is happening for a lot of users of an app, then it is most likely the API calls made through that app causing this. In this case, you should reduce their calls or spread them more evenly.

Profile Picture URLs

Profile picture URLs returned from the Graph API may have different rate-limits. When you reach these limits, the request will return an HTTP response code 429 (too many requests). If you are consistently hitting the rate-limit:

  • Spread your queries out evenly between multiple time intervals.
  • Load the picture client-side rather than server-side.
  • If you need to load the picture server-side, cache the picture.

FAQ

What do we consider an API call?

All calls count towards the rate limits, not just individual HTTPS API requests. For example, you can make a single API call and specify multiple ids, but each ID would count as its own API call, even though you are only making one HTTPS API request.

To illustrate this concept, see the examples below:

Example Request(s) Number of API Calls

GET https://graph.facebook.com/photos?id=4
GET https://graph.facebook.com/photos?id=5
GET https://graph.facebook.com/photos?id=6

3

GET https://graph.facebook.com/photos?id=4,5,6

3

In a scenario where you need to traverse multiple objects by ID, we strongly recommend you use the second approach as it will improve performance of your API responses, but it will not improve the number of calls made for the purposes of rate limiting.

You can also use the Batch API to batch your requests, but note that each sub-request is its own API call, or even multiple API calls in the case of specifying many ids.

If you app or page becomes rate limited, API calls that encounter rate limiting errors also count towards your rate limit.


What Errors Will My App See?
Throttling Type At least Error Code

Application-level throttling

200 calls/person/hour

4

Account-level throttling

Not applicable

17

Page-level throttling

4800 calls/person/24-hours

32

Custom-level throttling

Not applicable

613


I'm seeing Error Code 613, what do I do?

If your error response contains error_subcode 1996, Facebook has noticed inconsistent behavior in the API request volume of your app. If you have made any recent changes that affect the number of API requests, you may be encountering this error.

If you do not see the subcode, your app is exceeding a custom rate limit. Please contact your Partner Manager for help resolving this issue.


I'm building a scraper, is there anything else I need to worry about?

If you're building a service that scrapes data, read our scraping terms.