net.degreedays.api

Class RateLimitException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

net.degreedays.api.DegreeDaysApiException

net.degreedays.api.FailureException

net.degreedays.api.RequestFailureException

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

Modifier and Type	Method and Description
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

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, 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