net.degreedays.api

Class InvalidRequestException

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.InvalidRequestException

All Implemented Interfaces:

java.io.Serializable

public final class InvalidRequestException
extends RequestFailureException

Indicates that the API could not process a request because it was invalid in some way (e.g. authenticated with invalid access keys).

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

The isDueToInvalidRequestXXX() methods contained within this class make it easy to test for the "InvalidRequestXXX" codes that you are likely to want to test for. There are also several "InvalidRequestXXX" codes that do not have corresponding isDueToInvalidRequestXXX() convenience methods, but these codes should not arise through normal use of this Java client library. For example, there's an "InvalidRequestXml" code that you should never receive unless you have modified the mechanism that this Java client library uses to generate the XML requests (something you're unlikely to want to do).

All "InvalidRequestXXX" codes will cause this exception to be thrown, irrespective of whether they have their own isDueToInvalidRequestXXX() methods. If, for some reason, you need to explicitly check for an "InvalidRequestXXX" code that does not have its own isDueToInvalidRequestXXX() method, you can always check for it by testing the failure code string directly.

If you're testing the isDueToInvalidRequestXXX() methods, please do make sure that your code won't blow up if none of them return true.

See Also:

Failure codes, isDueToXXX() methods

Method Summary

Modifier and Type	Method and Description
boolean	isDueToInvalidRequestAccount() Returns true if this failure came in response to a request that was sent with an unrecognized account key.
boolean	isDueToInvalidRequestForAccountPlan() Returns true if this failure came in response to a request for data that is not available on the API account plan associated with the account key.
boolean	isDueToInvalidRequestSignature() Returns true if this failure came in response to a request that was sent with an invalid signature, typically caused by a problem with the security key.
boolean	isDueToInvalidRequestTimestamp() Returns true if this failure came in response to a request that was sent with an invalid timestamp, typically caused by an out-of-sync clock on the client machine.

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

isDueToInvalidRequestAccount

public boolean isDueToInvalidRequestAccount()

Returns true if this failure came in response to a request that was sent with an unrecognized account key.

The account key is a string that is used to uniquely identify a customer's API account. If the API receives a request containing an unrecognized account key (e.g. a key with a typo, or a key for an expired account), this type of failure will be sent back in the response.

The account key would typically be set in the constructor of DegreeDaysApi.

See Also:

Failure codes, isDueToXXX() methods, Access keys

isDueToInvalidRequestForAccountPlan

public boolean isDueToInvalidRequestForAccountPlan()

Returns true if this failure came in response to a request for data that is not available on the API account plan associated with the account key.

The Degree Days.net website has details of the different account plans and how to upgrade.

Since:

1.2

See Also:

Failure codes, isDueToXXX() methods

isDueToInvalidRequestSignature

public boolean isDueToInvalidRequestSignature()

Returns true if this failure came in response to a request that was sent with an invalid signature, typically caused by a problem with the security key.

Signatures are used as part of the key-based security mechanism that protects the usage quotas associated with customer accounts. This Java client library would typically generate all signatures automatically, so, unless you have customized the signature-generation process, this type of failure should only come about if a signature is generated using an erroneous security key (e.g. one that was entered with a typo).

The security key of the account would typically be set in the constructor of DegreeDaysApi.

See Also:

Failure codes, isDueToXXX() methods, Access keys

isDueToInvalidRequestTimestamp

public boolean isDueToInvalidRequestTimestamp()

Returns true if this failure came in response to a request that was sent with an invalid timestamp, typically caused by an out-of-sync clock on the client machine.

When a request is packaged up and sent to the API servers, a timestamp is included to indicate the time, in UTC (GMT), that the request was sent. This timestamp is checked against the server's clock as part of a system designed to prevent unwanted replays of previous requests.

This type of failure can occur if the client's clock is badly out of sync (like 15 minutes or more from the real time). If the computer's clock looks right, and you're still getting this type of failure, then it's possible that the computer's clock is set with the wrong time-zone. The timestamps sent to the server are UTC timestamps, and, unless the computer's time-zone is set correctly, its concept of UTC time is likely to be out by at least an hour.

See Also:

Failure codes, isDueToXXX() methods