Generally, an error is anything that happens during execution of DOTS Usage Reports that causes the service to fail. The source of these errors may be user input, license key transaction limits, timeouts, and unexpected circumstances. Applications should expect and handle any and all errors appropriately. Occasionally, new error types or descriptions may be introduced to the web service as new features and data sources are implemented. Description strings may change slightly, so use the description code to determine which error has occurred. Errors are organized into types, listed in the table below.
The Error object appears under the main return object. Below is an example of the error returned when the GetDOTSTransactionDetailsByDateRange operation is accessed without a valid license key.
Example:
<ReportTransactionDetailUsage> <Error> <Desc>License key and e-mail do not match our records.</Desc> <Number>2</Number> </Error> </ReportTransactionDetailUsage>
Error codes in Usage Reports are the same for all operations.
Error Code 1 – “Input cannot be less than zero length”
This error means the web service did not get any input. The connection to the service was made, and data was transferred, but no parameters were passed that the service could understand.
This error often happens when the input is passed to the service with namespaces that the service does not understand. Applying a namespace to any of the parameters (Address, City, State, etc.) will cause this error. Additionally, requests made in the “rpc/encoded” format will cause this error. The only namespace that should appear in any element is the “https://www.serviceobjects.com” namespace on the root Validate* element as so:
Note, however, that the namespace is not applied to the ReportTransactionDetailUsage element, it is only present.
Error Code 2 – Various descriptions
This error code appears when various errors occur but are of the expected nature. Oftentimes, maligned or incomplete input will cause an error 2. The following is a list of the possible Error Descriptions that may accompany an Error Code 2:
Bad or Incomplete GETDOTSTransaction Errors
Description
License Key is required.
Email is required.
License key and email do not match our records.
A valid Date is required.
Please enter a valid date range.
Failed Authentication Errors:
Description
Please provide a valid license key for this web service.
This license key has expired.
This license key has not yet been activated.
Web Service Invocation Errors:
Description
Error initializing service.
Error Code 3/4/5 – Various descriptions
An error code 3, 4, or 5 is a fatal error and it means something serious has gone wrong. You will never see one of these error codes in a live production environment.