Rate limiting of the standard API is primarily on a per-user basis — or more accurately described, per user access token. If a method allows for 15 requests per rate limit window, then it allows 15 requests per window per access token.

When using application-only authentication, rate limits are determined globally for the entire application. If a method allows for 15 requests per rate limit window, then it allows you to make 15 requests per window — on behalf of your application. This limit is considered completely separately from per-user limits.

15 Minute Windows

Rate limits are divided into 15 minute intervals. All endpoints require authentication, so there is no concept of unauthenticated calls and rate limits.

There are two initial buckets available for GET requests: 15 calls every 15 minutes, and 180 calls every 15 minutes.

HTTP Headers and Response Codes

Use the HTTP headers in order to understand where the application is at for a given rate limit, on the method that was just utilized.

Note that the HTTP headers are contextual. When using app-only auth, they indicate the rate limit for the application context. When using user-based auth, they indicate the rate limit for that user-application context.

• x-rate-limit-limit: the rate limit ceiling for that given endpoint
• x-rate-limit-remaining: the number of requests left for the 15 minute window
• x-rate-limit-reset: the remaining window before the rate limit resets, in UTC epoch seconds

When an application exceeds the rate limit for a given standard API endpoint, the API will return a HTTP 429 “Too Many Requests” response code, and the following error will be returned in the response body:

 { "errors": [ { "code": 88, "message": "Rate limit exceeded" } ] } 

To better predict the rate limits available, consider periodically using GET application / rate_limit_status. Like the rate limiting HTTP headers, this resource’s response will indicate the rate limit status for the calling context — when using app-only auth, the limits will pertain to that auth context. When using user-based auth, the limits will pertain to the application-user context.

GET and POST Request Limits

Rate limits on reads from the system (GET) are defined on a per user and per application basis, while rate limits on writes into the system (POST) are defined solely at the user account level. In other words, for reading rate limits consider the following scenario:

• If user A launches application Z, and app Z makes 10 calls to user A’s mention timeline in a 15 minute window, then app Z has 5 calls left to make for that window
• Then user A launches application X, and app X calls user A’s mention timeline 3 times, then app X has 12 calls left for that window
• The remaining value of calls on application X is isolated from application Z’s, despite the same user A

Contrast this with write allowances, which are defined on a per user basis. So, if user A ends up posting 5 Tweets with application Z, then for that same period, regardless of any other application that user A opens, those 5 POSTs will count against any other application acting on behalf of user A during that same window of time.

Lastly, there may be times when the rate limit values that are returned are inconsistent, or cases where no headers are returned at all. Perhaps memcache has been reset, or one memcache was busy so the system spoke to a different instance: the values may be inconsistent now and again. There is a best effort to maintain consistency, with a tendency towards giving an application extra calls if there is an inconsistency.

Tips to avoid being Rate Limited

The tips below are there to help you code defensively and reduce the possibility of being rate limited. Some application features that you may want to provide are simply impossible in light of rate limiting, especially around the freshness of results. If real-time information is an aim of your application, look into the Streaming APIs.

Streaming API

The Streaming API has rate limiting and access levels that are appropriate for long-lived connections. See the Streaming APIs documentation for more details.

Leveraging the Streaming API is a great way to free-up your rate limits for more inventive uses of the Twitter API.

Rate Limiting information for the Streaming API is detailed on Connecting to a streaming endpoint.  

Exponential back-off pattern for streaming:

If the initial reconnect attempt is unsuccessful, your client should continue attempting to reconnect using an exponential back-off pattern until it successfully reconnects.

Regardless of how your client gets disconnected, you should configure your app to reconnect immediately. If your first reconnection attempt is unsuccessful, we recommend that your app implement an exponential back-off pattern in subsequent reconnection attempts (e.g. wait 1 second, then 2 seconds, then 4, 8, 16, etc), with some reasonable upper limit. If this upper limit is reached, you should configure your client to notify your team so that you can investigate further.

Limits Per Window Per Resource

The API rate limit window duration is 15 minutes. Visit our standard API Rate Limit: Chart page to see the limits by resource.

Note that endpoints/resources not listed in the above chart default to 15 requests per allotted user.