net.degreedays.api
Class RateLimitException

java.lang.Object
  extended by java.lang.Throwable
      extended by java.lang.Exception
          extended by java.lang.RuntimeException
              extended by net.degreedays.api.DegreeDaysApiException
                  extended by net.degreedays.api.FailureException
                      extended by net.degreedays.api.RequestFailureException
                          extended by net.degreedays.api.RateLimitException
All Implemented Interfaces:
java.io.Serializable

public final class RateLimitException
extends RequestFailureException

Indicates that the API servers did not process a request because the RateLimit for the account's plan had been reached.

The best way to handle this exception is often to wait until the rate limit is reset. You can figure out how long that is from the RateLimit object, accessible through the responseMetadata(). Or you might want to consider upgrading your account to increase your rate limit. Visit the Degree Days.net website for more on this.

This exception corresponds to any failure code starting with "RateLimit".

You can interrogate the isDueToXXX() methods of this exception to find out more about the cause. There is only one such method at the moment, but more may be added in a future version of this client library.


Method Summary
 boolean isDueToRateLimitOnLocationChanges()
          Returns true if this failure was caused by a rate limit on the number of times a location-limited account can change the location(s) that they access data from.
 
Methods inherited from class net.degreedays.api.RequestFailureException
responseMetadata
 
Methods inherited from class net.degreedays.api.FailureException
failure, getMessage
 
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

isDueToRateLimitOnLocationChanges

public boolean isDueToRateLimitOnLocationChanges()
Returns true if this failure was caused by a rate limit on the number of times a location-limited account can change the location(s) that they access data from.

Location-limited accounts are low-end accounts that are used for fetching regular updates from a limited number of locations. The number of locations allowed depends on the location-limited account in question.

Allowed locations are set automatically. If a location-limited account successfully fetches data from a given location, that location is assigned to the account, and the account is able to continue fetching data from that location as time goes on (e.g. fetching daily/weekly/monthly updates).

A certain amount of location turnover is allowed. Offices and people move to new buildings, and occasionally weather stations go down and replacements need to be found (see LocationException.isDueToLocationNotSupported() for more on this). As new locations are added to an account's list of allowed locations, older locations are removed on a least-recently-used basis. There are limits on the number of "location changes" that a location-limited account can make in any given period of time. These limits aren't explicitly published, and may change over time, but the idea is that it should be very unlikely for a location-limited account to hit its limit on location changes. Location-limited accounts are built for a certain style of usage only (fetching regular updates from a mostly-fixed set of locations).

From a programming perspective, dealing with a rate limit on location changes is unlikely to be any different from dealing with the usual rate limit on the number of API requests. If you have a user-driven application, you might want to call this method to help you decide what message to show in the UI... But, if your program is a background task that fetches data at regular intervals, you probably won't need to distinguish between a limit on API requests (all accounts have these) and a limit on location changes (only location-limited accounts have these). If an account hits a rate limit (whether on requests or location changes), you'll get a RateLimitException e, and you'll generally just want to wait the specified number of minutes until the rate limit is reset ( e.responseMetadata().rateLimit().minutesToReset()).

See Also:
Failure codes, isDueToXXX() methods


www.degreedays.net/api/