Rate Limiting

Web Services only allows clients to make a limited number of calls in a given hour. The default rate limit for calls to a Resource permits 600 requests per hour. Calls are measured against the public facing IP of the server or device making the request. Every Resource in the documentation explains if it is rate limited or not.

Knowing if you are rate limited

If your application is being rate-limited it will receive HTTP 400 response codes. It is best practice for applications to monitor their current rate limit status and dynamically throttle requests if necessary.

You can check the rate limit one of two ways.

Response headers

Every time you make a request to Resource we will return the current rate status to you in the response header. You should look for the following header keys:

		X-RateLimit-Limit: 150
    	X-RateLimit-Remaining: 149
    	X-RateLimit-Reset: 1330819320
    	X-RateLimit-ResetTime: Sun, 04 Mar 2012 00:02:00 +0000
	

Request your rate limits from the API

Make a request call to /ws/v2.0/ratelimits. You will get a response similar to:

    	{
    		"pattern"=>"/time/CGT/",
    		"reset"=>1330819320,
			"remaining"=>149,
		    "limit"=>150,
		    "reset_time"=>"Sun, 04 Mar 2012 00:02:00 +0000"
	    }

	    <ratelimits version="0.1" total="1">
	    	<ratelimit pattern="/time/CGT/" limit="150" remaining="149" reset="1330819320" reset_time="Sun, 04 Mar 2012 00:02:00 +0000"/>
    	</ratelimits>
	

Once the rate limit reset time is reached, your remaining count will be reset the limit and everything will continue as it was before the rate limit was reached.

Whitelisting

Whitelising is currently not available. Resourceful use of more efficient requests will allow you to build your integration successfully without requiring whitelisting.

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.

Caching

Store responses in your application or on your site if you expect a lot of use. For example, don't try to call a Resource on every page load of your website landing page. Instead, call the Resource infrequently and load the response into a local cache. When users hit your website load the cached version of the results.

Prioritize active users

If your site keeps track of many users (for example, fetching their current status), consider only requesting data for users who have recently signed into your site.

Blacklisting

We ask that you honor the rate limit. If you or your application abuses the rate limits we will blacklist it. If you are blacklisted you will be unable to get a response from the SW Combine Web Services.

If you or your application has been blacklisted and you think there has been an error you can create a Support Ticket. So we can get you back online quickly please include the following information:

1. Make a call to the GET /ratelimiting from the account or computer which is blacklisted.
2. Explain why you think your application was blacklisted.
3. Describe in detail how you have fixed the problem that you think caused you to be blacklisted.