Skip to end of metadata
Go to start of metadata

API Usage Constraints

On This Page

Input and Output Throttling

To ensure good performance, all accounts are limited to 100 reads per minute and 60 writes per minute. This limit is enforced programmatically by the API on a member level. That means if there are two API users for a single member, they will share the throttling limit (i.e., two users can average 50 reads per minute each, four users can average 25 reads per minute each). If you require more reads or writes per minute, please reach out to your AppNexus account representative.

Error Messages

If you exceed the throttling limit, the API will respond with the HTTP 429 (Too Many Requests) response code along with an error message in the response contents. An example of the error message is shown here:

Rate Limit exceeded Response


If you're using a script, you should check for the 429 response code. If you receive this code, sleep your script for the number returned in the Retry-After field of the response header. This field tells you how long before your throttle limit is reset and you can continue processing API commands.

429 Error Header


Debug Parameter

In addition to the response code and response header, every response from the API will contain a dbg_info parameter. This parameter contains information about the API call and response. Below is an example of this debug output, which includes any warnings received from the API, the API version used for the call that generated this response, and the service used. 


Pagination

The maximum number of objects that can be returned in a given GET response is 100. To retrieve more than 100 objects, you can paginate results by specifying start_element and num_elements in the query string of the GET request. For example, the following request would return the first 50 objects in the response:

To retrieve the next 50, you would simply set start_element=50.

  • The first element is element 0.
  • All GET responses will have a "count" property showing the total number of elements matching that GET request.
  • This will also apply to non-reporting services, such as the creative search service, that are requested with methods other than GETs.

Examples

Authentication Frequency

After authenticating, your token remains valid for 2 hours. You do not need to re-authenticate within this time. If you do re-authenticate, please note the following limitation: The AppNexus API permits you to authenticate successfully 10 times per 5-minute period. Any subsequent authentication attempts within those 5 minutes will result in an error.

It is best practice to listen for the "NOAUTH" error_id in your call responses and re-authenticate only after receiving it.

Request Length

API requests can be a maximum of approximately 6500 characters. If your request is too long you'll receive an error message similar to this: 

To resolve this issue, break your request into multiple, smaller requests.

Object Limits

AppNexus limits the number of line items, campaigns, creatives, publishers, sites, and placements that you can have on the platform. In addition, AppNexus limits the number of domains that can be used in a single domain list and the number of certain targets that can be used in a single profile. You can use the Object Limit Service to view your limits and proactively monitor your usage.

For all object types except creatives, both active and inactive objects are counted against the limit. For creatives, only non-expired objects are counted against the limit. A creative expires when it has neither served nor been modified in 45 days.

For most clients, the default object limits are as follows:

Object

Limit

Creatives per member
Note: Only non-expired creatives are counted against this limit.

10,000

Campaigns per member

10,000

Line items per member

3,000

Placements per member

20,000

Sites per member

10,000

Publishers per member

3,000

Domains per domain list

30,000

Segments targeted per profile

400

Segment groups targeted per profile

400

Content categories targeted per profile

300

Platform content categories targeted per profile

300

Postal codes targeted per profile

4000

Inventory sources targeted per profile

Deprecated

Publishers targeted per profile

300

Placement Groups targeted per profile

100

Placements targeted per profile

250

FAQs

How will I know that I am approaching my limit for an object?

We send you an email notification when you reach 85% and 95% of your limit for an object and another email when you reach 100% of your limit.

Who receives object limit email notifications?

Object limit notification emails are sent to the email addresses specified in the sherlock_notify_email field of the Member Service. You can change the recipients at any time. Note, however, that this field controls the recipients for creative auditing emails as well.

What if I reach my limit for an object?

When you approach or reach your limit for campaigns, line items, placements, sites, or publishers, you should delete any inactive, unused, or unnecessary instances so you can stay under your limit. You can use the Advertiser Cleanup tool to bulk-delete objects (customer login required). Deleted line items, campaigns, creatives, publishers, sites, and placements will continue to appear in reporting but cannot be undeleted.

When you approach or reach your limit for creatives, you should remove non-expired creatives. Non-expired creatives have the is_expired field set to false. Note that removing expired creatives will not impact your creative count.

What if I am already over my limit?

If you need to create additional objects but have already met or exceeded your limit as listed above, please delete unused objects or contact support for assistance. Our support team can help you identify inactive objects to delete.

Can my limit be raised?

In exceptional cases, a limit may be temporarily lifted by a small amount at the discretion of our engineering team. Please contact your AppNexus representative to discuss this option.