• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!

View
 

Rate limiting

This version was saved 14 years, 11 months ago View current version     Page history
Saved by Doug Williams
on April 7, 2009 at 2:47:34 pm
 

<< Back to the Orientation

 

Rate limiting

The Twitter API only allows clients to make a limited number of calls in a given hour. This policy affects the two APIs in different ways. 

 

REST API Rate Limiting

The default rate limit for calls to the REST API is 100 requests per hour. The REST API does account- and IP-based rate limiting. Authenticated API calls are charged to the authenticating user's limit while unauthenticated API calls are deducted from the calling IP address' allotment.

 

Rate limiting only applies to methods that request information. API methods that use HTTP POST to submit data to Twitter, such as statuses/update do not affect rate limits. Additionally, requests to account/rate_limit_status are not charged to a limit. These unlimited methods are still subject to daily update and follower limits to promote healthy use and discourage spam.

 

Your application should recognize it is being rate-limited by the REST API if it receives begins to receive HTTP 400 response codes.

 

It is best practice for applications to monitor their current rate limit status and dynamically throttle requests if necessary. The REST API offers two ways to observe this status:

 

  1. The account/rate_limit_status method. Calling this method does not count against the requestor's API limit.
  2. HTTP response headers included in all REST API responses: 
  • X-RateLimit-Limit the current limit in effect
  • X-RateLimit-Remaining the number of hits remaining before you are rate limited
  • X-RateLimit-Reset the time the current rate limiting period ends in epoch time.

 

Whitelisting

Some applications find that the default limit proves insufficient. Under such circumstances, we offer whitelisting which will raise an accout or IP address' rate limit to 20000 requests per hour. If you are developing an application that should be considered for whitelisting, please fill out the whitelisting request form. Our manual review process can take up to a week. If you have a whitelisting that needs to be updated through the addition or removal of IP addresses, reapply with an explanation of the change.

 

IP whitelisting takes precedence to account rate limits. Requests from a whitelisted IP address made on a user's behalf will be deducted from the whitelisted IP's limit, not the users. Therefore, IP-based whitelisting is a best practice for applications that interact with many users' data.

 

 

Search API Rate Limiting

The Search API is rate limited by IP address. The number of search requests that originate from a given IP address are counted. The specific number of requests a client is able to make to the Search API for a given hour is not released. However we feel it is liberal and sufficient for most applications.

 

An application that exceeds the rate limitations of the Search API will receive HTTP 503 response codes to requests. It is a best practice to watch for this error condition and honor the Retry-After header that instructs the application when it is safe to continue.

 

Whitelisting

There is no general idea of a whitelist for the Search API as with the REST API. However, under extraordinary circumstances we work with developers to raise rate limiting for Search requests. If you feel that your application is doing everything it can to limit and combine queries where appropriate, please contact Twitter to discuss your needs.

 

Avoiding the Rate Limiter

The same general techniques and design decisions can be used to avoid the crunch of the rate limiter.

  1. Caching: Store API responses in your application or on your site if you expect high-volume usage. For example, don't try to call the Twitter API on every page load of your hugely popular website. Instead, call our API infrequently, cache the response on your end, and display the local version on page loads.
  2. Prioritize active users: If your site keeps track of many Twitter users (for example, fetching their current status or statistics about their Twitter usage), consider only requesting data for users who have recently signed into your site.
  3. Search back-offs: If your application monitors a high volume of search terms, query less often for searches that have no results than for those that do. By using a back-off you can keep up to date on queries that are hot but not waste cycles requesting queries that very rarely change.

 

Blacklisting

We ask that you honor the rate limit. Consistent failure to avoid the rate-limiter will signal Twitter to automatically blacklist your application. You know that you are blacklisted if your client is unable to get a response for a request sent to the API. It appears as if API calls are sent down a blackhole.

 

If your application has been blacklisted and you would like service reinstated please do the following:

  1. If you are using the REST API, make a call to the account/rate_limit_status from the account or computer in question.
  2. Explain why you think your application was blacklisted.
  3. Describe how you have fixed the problem that resulted in blacklisting.

Send that information in an email to our support folks so we can get you back online.

 

 

Comments (0)

You don't have permission to comment on this page.