Understanding responses

Responses to requests are standard HTTP responses. The body of the response is structured using XML, containing either relevant data or an exception if something went wrong.

A 200 OK HTTP status code will be returned if the request could be processed.

Refer to the function reference for details of the responses for the function you are using.

HTTP status codes used

200 OK: Standard response code for successful requests.
403 Forbidden: Requesting IP address has been blocked.
405 Method Not Allowed: HTTP METHOD not allowed for given resource. This status code will be returned when you try to GET what should be POSTed or POST what should be GETed.

Exceptions

Exceptions will be raised if the problems are encountered in handling a request. This may happen if there is a fault, such as failing to connect to the database, or if you supply incorrect query values.

All exceptions will be contained in an exception element containing type, message and code elements.

The unique combination of type and code allows you to determine what went wrong, letting your application respond gracefully to errors.

type

access
account
database
hostingaccount
server
system

message

A worded description of the error that occurred. This is intended for your understanding of what went wrong and may change over time. This should not be programmatically interpretted.

code

A three digit number identifying the error that occurred. This is intended to inform your program of what went wrong and will never change over time.

Example: making a request from a banned IP

GET /price/getBandwidth/

<?xml version="1.0" encoding="utf-8"?>
<exception>
  <type>apiAccess</type>
  <message>Access not permitted from source IP.</message>
  <code>100</code>
</exception>

apiAccess

Raised when an error occurs in accessing the API.

100: key invalid: Specified key does not exist. It may have once existed but since been deleted.
101: key suspended: Access to the API from the specified key has been suspended.
102: key not allowed to access specified resource: Specified key does not have permission to access to the requested resource.
103: request limit reached: Monthly limit reached for requesting IP.
104: invalid email address or password: Authentication failure trying to retrieve key for an account.
99: unknown: An unexpected, unknown error occurred. We'd appreciate it if you'd contact us if this ever happens.

account

Raised for errors related to your account, such as if you try to add a new hosting account but don't have any credit remaining to pay for its usage.

101: Action disallowed - balance is zero or less

Certain actions require your balance to be greater than zero, such as adding a new hosting account or making any one-off purchase.

105: Account email address has already been verified

You must verify your email address before we can active your account. This exception will be raised if you have already verified your email address and attempt to do so again.

200: Password reset failed

Password reset request failed due to an internal fault. This is a precautionary error catching condition that has never occurred when testing under normal conditions.

This is not the same as a password reset failing due to incorrect credentials. In such conditions, account::reset_password will return false.

201: Chosen new email address is taken

If you choose to change your account email address it may be the case that another account is using the email address you chose.

99: unknown

An unexpected, unknown error occurred. We'd appreciate it if you'd contact us if this ever happens.

database

Faults in connecting to and communicating with one of the backend databases. The message for database exceptions is always blank.

Please tell us if this happens lots. Repeated database exceptions may indicate a serious fault.

hostingaccount

The code values 100 - 105 relate to adding hosting accounts. Values 200 - 202 relate to the modification of existing hosting accounts.

Please tell us if you encounter code values 104 or 105. These indicate significant faults.

100: User name invalid
101: Domain name invalid
102: Domain name taken
103: User name taken
104: No working servers found: A new hosting account is added to the least utilised server at the time. This exception will be raised if no servers in our hosting cluster were found to be working. This is a significant fault.
105: All servers have reached their storage limits: No hosting servers have any storage space left. This is a significant fault.
200: Hosting account password reset failed: An account password reset request failed to reset the password. This is a precautionary error catching condition that has never occurred when testing under normal conditions.
201: Action denied as hosting account is suspended: Certain actions are not allowed to be performed on a suspended hosting account. This currently includes only resetting a hosting account's password.
202: Action denied as hosting account has been deleted: Raised when you try to do something to a hosting account that no longer exists.
99: unknown: An unexpected, unknown error occurred. We'd appreciate it if you'd contact us if this ever happens.

server

100: server not found: Happens when you try to request the details of a hosting server that does not exist.
99: unknown: An unexpected, unknown error occurred. We'd appreciate it if you'd contact us if this ever happens.

server

100: unknown system error: Either something odd happened or an error condition we hadn't considered occurred. We'd appreciate it if you'd contact us if this ever happens.