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

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

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. For more information about rate limiting in Graph API, see Rate Limiting on the Graph API.

API-Level Limits

  • Rate limiting is at the ad account level.
  • Rate limitation happens real time on a sliding window.
  • Each Marketing API call is assigned a score. Your score is the sum of your API calls.
  • Updates are 10~100 more expensive than creates.
  • There's a max score, and when it's is reached, the throttling error is thrown.
  • Error, Code: 17, Message: User request limit reached

Recommendations:

  • Verify the error code (17) and api end point to confirm the throttling type.
  • The call will be blocked for a minute.
  • During this time the max score will decay, being dropped to 0 after a maximum of 5 minutes.
  • Switch to the other ad accounts and come back to this account later.
  • It is better to create a new ad than to change the existing ones.

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.

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.

Datafile Custom Audience Rate Limits

We enforce rate limits on the number of API calls an ad account has to add or remove users in a data file for custom audiences per 24-hour period. To prevent user data leakage, you cannot remove users in a data file custom audience too frequently. When you reach a rate limit error, we temporarily block you from updating the data file custom audience.

You can determine what your limits are, make a GET request at /act_{adAccountID}/custom_audience_limits:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/custom_audience_limits"

The response includes:

Name Type Description

has_hit_audience_update_limit

bool

Whether an ad account reached the daily update limit for a custom audience.

next_audience_update_available_time

datetime, as UTC UNIX timestamp

Next time you are allowed to update the custom audience

audience_update_quota_left

int

Number of update calls you can make for ad account before you reach the daily limit for an audience.

audience_update_quota_in_total

int

Maximum number of daily custom audience update calls the ad account can make.

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.

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.