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.

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.RateLimitTrackerOption = RateLimitTrackerOptions.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.
• In the other hand this solution is a bit more complex to implement.

// Enable RateLimit Tracking
RateLimit.RateLimitTrackerOption = RateLimitTrackerOptions.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!
    }
};