Best Practices

  • Rate Limiting - Different rate limits on the API and how to deal with them
  • Async Requests - How to use asynchronous requests for creating ads
  • Batch Requests - Batch your API calls for greater efficiency
  • Storing and retrieving objects - Campaign, ad set, and ad objects limit the number of each object allowed in an ad account. Manage objects around those limits
  • Error codes - Common error codes the API returns
  • eTags - Optimize your calls to only fetch data when it changed
  • Validation - Validation that occurs amongst the ad objects and parameters

General

Ad Changes Triggering Ad Reviews

If you make any changes to the following scenarios, your ad will be triggered for review:

  • Any changes to your creative (image, text, link, video, and so on)
  • Any changes to targeting
  • Any changes of optimization goals and billing events may also trigger review

Note: Changes to bid amount, budget, and ad set schedule will not have any effect on the review status.

Additionally, if an ad enters Ad Review with the run status of "Paused", then it will remain Paused upon exiting Ad Review. Otherwise, the ad will be considered Active and ready to deliver.

Pagination

For paging response data, see the Graph API Pagination.

User Information

You should store user IDs, session keys, and the ads account ID so it is easy to programmatically access them and keep them together. This is important because any calls made with an account ID belonging to one user and the session key for another user will fail with a permissions error.

Suggested Bids

Run frequent reports on your campaigns, as suggested bids change dynamically in response to bidding by competitors using similar targeting. Bid suggestions get updated within a few hours, depending upon the bidding of competitors.

Batch Requests

Make multiple requests to the API with a single call, see:

You can also query for multiple objects by ID as follows:

https://graph.facebook.com/<API_VERSION>?ids=[id1,id2]

To query for a specific field:

https://graph.facebook.com/<API_VERSION>?ids=[id1,id2]&amp;fields=field1,field2

Check Data Changes using ETags

Quickly check if the response to a request has changed since you last made it, see:

Object Archive and Delete Status

Ad objects have two types of delete states: archived and deleted. You can query both archived and delted objects with the object id. However, we do not return deleted objects if you request it from another object's edge.

You can have up to 5000 archived objects at any time. You should move ad objects from archived states to deleted states if you no longer need to retrieve them via edges. To learn how states work and for sample calls see Storing Ad Objects.

Viewing Errors

People make mistakes and try to create ads that are not accepted, Error Codes provide reasons an API call failed. You should share some form of the error to users so they can fix their ads.

Facebook Marketing Developer Community Group

Join Facebook Marketing Developer Community group on Facebook for news and update on for Marketing API. We post items from the Marketing API blog to the group.

Rate Limiting

The Marketing API has it is 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 Rate Limit dashboard in the app dashboard shows the current percentage of the limit used and time to reset usage. We recommend that you check the current percentage of the limit used and time to reset usage in the app dashboard. If the usage is close to the limit, reduce the number of Marketing API calls.

For more information about rate limiting in Graph API, see Rate Limiting on the Graph API.

API-Level Limits

See Ad Account Level Rate Limiting.

  • 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, and when you reach it, we throw a throttling error.
  • Updates are 10~100 more resource intensive than creates.
  • Error, Code: 17, Message: User request limit reached.

For the Insights API rate limits, see Ads Insights Level Rate Limiting

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
  • When the max score is reached, the throttling error is thrown
  • Error, Code: 4, Message: Application request limit reached
  • App Level Rate Limiting is enforced
  • When the error is encountered, scale back your calls

Ad Account Level Limits

  • Number of changes to the ad account spend_cap, spend_cap_action fields are limited.
  • Error, Code: 17, Message: User request limit reached.
  • Verify the error code (17) and API end point to confirm the throttling type.
  • When this error is encountered, scale back the changes to the ad account.
  • 90-days from the release of v3.3 and effective for all public versions, we change the ad account level rate limit to better reflect the volumne of API calls needed. We compute the rate limit quota on your Marketing API access tier and the business owning your app. see Access and Authentication. This change applies to all Ads Insights API endpoints: GET {adaccount_ID}/insights, GET {campaign_ID}/insights, GET {adset_ID}/insights, GET {ad_ID}/insights, POST {adaccount_ID}/insights, POST {campaign_ID}/insights, POST {adset_ID}/insights, POST {ad_ID}/insights.
  • ads_management - As of v4.0, for each ad account in a one-hour time period: (100000 if your app is in the Standard tier or 300 if your app is in the Dev tier) + 40 * Num of Active ads.
  • custom_audience - As of v4.0, for each ad account in a one-hour time period: No more than 700000. No less than 190000 if your app is in the Standard tier or 5000 if your app is in the Dev tier + 40 * Number of Active custom audiences.

Ad Set Level Limits

  • Number of changes to the ad set daily_budget, lifetime_budget fields are limited. For each ad set, the budget is only allowed to change 4 times per hour, if exceeds the limit, the budget change for that ad set will be blocked for an hour.
  • Error, Code: 17, Message: User request limit reached.
  • Verify the error code (17) and api end point to confirm the throttling type.
  • When this error is encountered, scale back the changes to the ad set.

Ad Level Limits

  • Number of ad creation is limited for a given ad account based on the daily spend limit.
  • Error, Code: 1487225, Message: User request limit reached.
  • Verify the error code (1487225) and api end point to confirm the throttling type.
  • When this error is encountered, scale back the changes.
  • You can also increase the daily spend limit.

Troubleshooting

API Errors

  • You can see the error rate by going to this dashboard at https://www.facebook.com/analytics/<YOUR_APP_ID>?section=apis
  • Check the error codes in Marketing API, Error Reference

Throttling Errors

Testing

Sandbox mode is a testing environment to read and write Marketing API calls without delivering actual ads. See Sandbox Mode for Developers

Try API calls with Graph API Explorer. You can try any API call you would like to make to the Marketing API, see blog post. Select your app in App, and grant your app ads_management or ads_read permission in extended permissions when you create an access token. Use ads_read if you only need Ads Insights API access for reporting. Use ads_management to read and update ads in an account.

For development and basic access, configure a list of ad accounts your app is able to make API calls for, see account list.

You can use sandbox mode to demonstrate your app for app review. However in sandbox mode you cannot create ads or ad creative. Therefore you should use hard coded ad IDs and ad creative IDs to demonstrate your use of our API for app review.

Basic Criteria

  • Demonstrate value beyond Facebook's core solutions, such as Facebook Ads Manager.

  • Focus on business objectives, such as increase in sales. Facebook business objectives can be found here.

Facebook Policies

Understand the API policies; Facebook has the right to audit your activity anytime:

Be ready to adapt quickly to changes. Most changes are versioned and change windows are 90 days, ongoing.

In Statement of Rights and Responsibilities, you are financially and operationally responsible for your application, its contents, and your use of Facebook Platform and the Ads API. You should manage your app's stability and potential bugs.