API Marketing

Marketing API Rate Limiting

The Marketing API has its own rate limiting logic and is excluded from all the Graph API rate limitations. So if you make a Marketing API call, it won't be calculated into the Graph API throttling.

The feature that impacts the Marketing API rate limit quota is Ads Management Standard Access. When you add the Marketing API product in your App Dashboard, you will get the Standard Access of Ads Management Standard Access by default. This will give you development access to the Marketing API. If you need to upgrade to get more rate limiting quota, upgrade to the Advanced Access of Ads Management Standard Access in App Review.

Marketing API AccessAds Management Standard AccessCapacity

Development access

Standard access

Basic rate limiting quota

Standard access

Advanced access

More rate limiting quota

Most Marketing API requests, and Pages API requests are subject to Business Use Case (BUC) Rate Limits and depend on the endpoints you are querying. You should be able to figure this out by checking if your HTTP request contains an X-Business-Use-Case header. See more details in Business Use Case Rate Limits.

Ad Account Level API-Level Limits

  • Rate limiting is at the ad account level.
  • Rate limits happen in real time on a given time range.
  • Each Marketing API call is assigned a score. Your score is the sum of your API calls.
  • We enforce a maximum score. Generally speaking, a read API call is equal to 1 point, and a write API call is equal to 3 points, and when you reach the maximum score, we throw a throttling error.
  • If your app is in the Marketing API development tier, your maximum score is 60, will decay in 300 seconds, and will be blocked for 300 seconds.
  • If your app is on the Standard tier of the Marketing API, your maximum score is 9000, will decay in 300 seconds, and will be blocked for 60 seconds.

Related error code: 17, Error subcode: 2446079, Message: User request limit reached. 613, Error subcode: 1487742, Message: There have been too many calls from this ad-account. Please wait a bit and try again.

Ads Insights Platform Rate Limiting

  • Rate limiting is at the application level.
  • Rate limiting is determined by the capacity of backend infra and downstream services.
  • When your app is rate limited, all Ads Insights API calls for the app are limited.
  • App Level Rate Limiting is enforced.

Related error code: 4, Error subcode: 1504022 or 1504039, Message: There have been too many calls from this app. Wait a bit and try again.

When this error is encountered, scale back your calls.

App-Level Limits

  • Rate limiting is at the application level.
  • Rate limiting is determined by total users of an app.
  • When your app is rate limited, all calls for the app are limited.
  • App Level Rate Limiting is enforced.

Related error code: 4, Message: Application request limit reached.

When this error is encountered, scale back your calls.

Ad Account Level Business Use Case Rate Limits

We compute the rate limit quota based on your Marketing API access tier and your app.

  • Rate limiting is at the ad account level and quota is computed based on your app ads api access tier.
  • ads_management - For each ad account in a one-hour time period: (100000 if your app is in the Marketing API Standard tier or 300 if your app is in the Dev tier) + 40 * Num of Active ads.
  • custom_audience - For each ad account in a one-hour time period: No more than 700000. No less than 190000 if your app is in the Marketing API Standard tier or 5000 if your app is in the Dev tier + 40 * Number of Active custom audiences.
  • ads_insights - For each ad account in a one-hour time period: (190000 if your app is in the Ads API Standard tier or 600 if your app is in the Dev tier) + 400 * Number of Active ads - 0.001 * User Errors.
  • Catalog Management - For each ad account in a one-hour time period: 20000 + 20000 * log2(unique users).
  • Catalog Batch - For each ad account in a one-hour time period: 200 + 200 * log2(unique users).
  • Your Marketing API rate limit may also be determined by Total CPU time and Total Wall time on your ad account. You will have more quota If your app has Marketing API Standard Access, for more details, check the HTTP [X-Business-Use-Case](/docs/graph-api/overview/rate-limiting/#headers-2) header and Business Use Case Rate Limits.

Related error code: 80000, 80003, 80004, 80014, Message: There have been too many calls from this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.

Verify the API endpoint and HTTP X-Business-Use-Case header to confirm the throttling type. See more details in Business Use Case Rate Limits. When this error is encountered, scale back the changes to the ad account.

Ad Account Level Ad Spend Rate Limits

We limit you to changing your account spending limits 10 times per day to ensure the Ads delivery performance.

  • Number of changes to the ad account spend such as spend_cap, spend_cap_action fields are limited

Related error code: 17, Error subcode: 1885172, Message: You can only change your account spending limit 10 times per day. Please wait to make more changes.

Ad Set Level Limits

The number of changes to the ad set daily_budget and lifetime_budget fields are limited. For each ad set, the budget is only allowed to change 4 times per hour, if it exceeds the limit, the budget change for that ad set is blocked for an hour.

Related error code: 613, Error subcode: 1487632, Message: You can only change your ad set budget 4 times per hour. Please wait to make more changes.

When this error is encountered, scale back the changes to the ad set.

Ad Level Limits

Ad creation is limited for a given ad account based on the daily spend limit.

Related error code: 1487225, Message: User request limit reached.

Verify the error code (1487225) and API endpoint to confirm the throttling type. When this error is encountered, scale back the changes. To increase your limit, you can also increase the daily spend limit.

Abuse Prevention Rate Limits

When our system detects that certain ad accounts generate a large amount of abnormal traffic, in order to protect the stability of the system and ensure the experience of other users, we will temporarily reduce the API Rate Limit quota of the abnormal accounts. Please try contacting Meta support for help.

Related error code: 613, Error subcode: null, Message: (#613) Calls to this api have exceeded the rate limit.

The difference between this and the Ad Account Level API-Level Limit is this error doesn't contain error subcodes. When this error is encountered, investigate if any action is triggering excessive API requests and contact Meta support for help.

Handle Throttling Errors

Initial Assessment

Check the Marketing API Access Tier:

By default, apps have development_access to the Marketing API. To find out which tier you are in, you can go to the App Review dashboard. You are in the development tier of Marketing API access if you have Standard Access to the Ads Management Standard Access feature. You are in the standard tier of Marketing API access if you have Advanced Access to the Ads Management Standard Access feature. You can also check your HTTP header and look for ads_api_access_tier in your X-Ad-Account-Usage, X-Business-Use-Case or X-FB-Ads-Insights-Throttle header.

If you keep getting rate limiting errors, consider upgrading to the standard_access of the Ads Management Standard Access. To get to the standard tier and get a higher rate limit quota, you can apply for Advanced Access to the Ads Management Standard Access feature in your App Review dashboard.

  • Check Error Codes: Determine the specific error codes related to throttling in the API response.
  • Check HTTP headers:
    • X-Ad-Account-Usage contains acc_id_util_pct, reset_time_duration and ads_api_access_tier.
    • X-Business-Use-Case contains call_count, total_cputime, total_time and estimated_time_to_regain_access, etc. info for the Business Use Case endpoint.
    • X-FB-Ads-Insights-Throttle contains app_id_util_pct, acc_id_util_pct and ads_api_access_tier for the Ads Insights API endpoints.
  • Check App Dashboard: We provide consoles in the App Dashboard that provides developers with in-depth insight into the rate limiting system and helps them diagnose and prevent rate limiting issues.

Identify the Cause

  • Rate Limits: Understand Meta Marketing API rate limits for the different endpoints being used and verify if the number of API requests is within the allowed limits for the application.
  • Burst Limits: Check if burst limits are causing issues during peak usage times. Usually burst traffic will cause Ad Account Level API-Level Limits (Related error codes: 17, 613).
  • Misoperations: Investigate if any misoperations are triggering excessive API requests.

Mitigation Steps

  • Prevent Burst Traffic: Distribute API requests evenly to avoid throttling caused by a large number of accesses in a short period of time.
  • Optimize Requests: Combine multiple smaller requests into batch requests, either IDs batch or async request to minimize the total number of API calls.
  • Backoff Strategy: Implement exponential backoff when receiving throttling errors, gradually increasing the time between retries. You can also examine HTTP headers for the reset time estimation.

Other Mitigation Tips

  • Understand if there is a need for this and reduce these calls if unnecessary.
  • For endpoints supporting async requests such as Ads Insights API, use Asynchronous Requests to query a huge amount of data.
  • You can also try to pass a list of ids if you need to query multiple same types of ad objects.
  • For Insights API, use Level Parameters or filtering to reduce the number of calls.