Rate Limits

Overview

RateLimits is a very important concept to understand when developing an application for Twitter. When a user authorizes a Twitter application to use its account, Twitter emits an OAuthToken that is used in each of the query performed on the REST API.

Each token is limited to access Twitter resources. For example a token can perform 180 searches in 15 minutes intervals. If you try to do more than 180 searches in the 15 minutes timeframe the REST API will return an exception.

Therefore it is critical for developers to understand how to manage RateLimits. This topic is so important that Tweetinvi provides powerful tools to manage RateLimits.

Please Note that by default Tweetinvi does not handle rate limits as it requires to perform additional WebRequests.

Quick Access:

• Automatic RateLimit Handling
• RateLimit Tracking
• Manual Handling and Tools

References:

• Rate Limits Description
• Rate Limits per endpoint

Let's code

First thing to note is that Tweetinvi does NOT handle RateLimits for you by default. It means that if a query fails Tweetinvi will either throw a TwitterException or return null to your request (click for more details on exception handling).

Automatic RateLimit Handling

The library is capable of tracking the RateLimits and waiting for these to be available to continue performing any operation.

This is the recommended solution for most developers as long as they make sure that their code properly uses Tweetinvi in async methods.

• The good part of such solution is that it frees developers from having to manage RateLimits.
• The bad part of this solution is that it freezes the thread executing the operation until a request token is available to execute the query. At such point the query is executed. It means that a single operation can take up to 15 minutes!

// Enable Automatic RateLimit handling
RateLimit.RateLimitTrackerMode = RateLimitTrackerMode.TrackAndAwait;

RateLimit Tracking

The second option provided by Tweetinvi is the RateLimit tracking. In other words, Tweetinvi will internally keep track of the RateLimits based on all the queries executed. This tracking is a good way to keep track of the RateLimits because it prevents you from

• This solution is a good compromise between Manual and Automatic RateLimit handling. It allows a developer to rely on Tweetinvi to keep track of the RateLimits whilst deciding what to do when RateLimits have been exhausted.
• On the other hand this solution is a bit more complex to implement.

// Enable RateLimit Tracking
RateLimit.RateLimitTrackerMode = RateLimitTrackerMode.TrackOnly;

TweetinviEvents gives you the ability to check the RateLimits and decide of a strategy to adopt concerning a query.

TweetinviEvents.QueryBeforeExecute += (sender, args) =>
{
    var queryRateLimits = RateLimit.GetQueryRateLimit(args.QueryURL);
	
	// Some methods are not RateLimited. Invoking such a method will result in the queryRateLimits to be null
    if (queryRateLimits != null)
    {
        if (queryRateLimits.Remaining > 0)
        {
            // We have enough resource to execute the query
            return;
        }

        // Strategy #1 : Wait for RateLimits to be available
        Console.WriteLine("Waiting for RateLimits until : {0}", queryRateLimits.ResetDateTime.ToLongTimeString());
        Thread.Sleep((int)queryRateLimits.ResetDateTimeInMilliseconds);

        // Strategy #2 : Use different credentials
        var alternateCredentials = TwitterCredentials.CreateCredentials("", "", "", "");
        var twitterQuery = args.TwitterQuery;
        twitterQuery.OAuthCredentials = alternateCredentials;

        // Strategy #3 : Cancel Query
        args.Cancel = true;

        // Strategy #4 : Implement yours!
    }
};

Manual Handling

Before we even start looking into a manual solution for RateLimit handling I would like to make clear that this solution is NOT recommended. RateLimits are complicated enough as is, I have to advise developers to avoid managing them manually.

Firstly we want to disable any RateLimit handling system.

// Default value of the RateLimit Tracker
RateLimit.RateLimitTrackerMode = RateLimitTrackerMode.None;

Tools

Here are some useful methods that you can use to simplify your life with RateLimits.

// Get RateLimits from credentials
var rateLimits = RateLimit.GetCurrentCredentialsRateLimits();
var rateLimits = RateLimit.GetCredentialsRateLimits(credentials);

// When you have a rateLimits object you can get the value of the RateLimit you want to verify
var userLookupLimits = rateLimits.UsersLookupLimit;

// Instead of having to identify the correct RateLimit, you can use GetQueryRateLimit
var queryRateLimits = RateLimit.GetQueryRateLimit("https://my_super_query");

// Finally you can easily wait for query rate limits to be available
RateLimit.AwaitForQueryRateLimit(queryRateLimits);
RateLimit.AwaitForQueryRateLimit("https://my_super_query");

Manual Handling Tutorial

Managing RateLimits means managing Exceptions to detect RateLimits issues. Therefore we will need to disable the ExceptionHandler.

ExceptionHandler.SwallowWebExceptions = false;

Doing so will result in making sure that all Twitter operation is safely surround in a WebException try/catch.

try
{
    // Your twitter call; for example lets use GetUser
    var tweetinvi = User.GetUserFromScreenName("tweetinviapi");
}
catch (WebException wex)
{
    var statusCode = -1;
    var wexResponse = wex.Response as HttpWebResponse;
    if (wexResponse != null)
    {
        statusCode = (int)wexResponse.StatusCode;
    }

    if (statusCode == TweetinviConsts.STATUS_CODE_TOO_MANY_REQUEST)
    {
        // The RateLimit is exhausted. Perform your code to manage it!
    }
}