When you make a request to the API, it will respond like a normal HTTP response.
Your programming language will probably provide an easy way to parse the response, however it could be useful to understand how the response is constructed.
Response header status
Just like a web server, the REST API will provide response headers with a status code and status message. The most useful of these is the status code.
The status code will indicate whether the request was successful or not. A '200' status code means a successful request, all other codes indicate an error was encountered. The full list of status codes is found below.
OK. We were able to successfully execute the requested operation.
Bad request. There was a problem with your request data, see the status message for details.
Incorrect username/password, or you do not have sufficient rights to access the specife resource.
|404||The specified resource could not be found.|
The specified method (GET, POST, PUT or DELETE) is not available for this resource.
|500||An unexpected error occurred|
|501||The method requested has not been implemented.|
Service Unavailable. The Web Service is not currently available to serve your request.
Error 503 may be returned if you exceed a certain number of requests per minute. You will see an error message similar to: “Your 201 requests exceed the maximum allowed of 100 requests within 15 minute(s). Please try again later”. This is to reduce load on our servers, in order to guarantee a good service to all our users.
There is no restriction on SMS sends, and you are very unlikely to ever see this message unless you are accidentally repeating calls to the API, such as due to an infnite loop.
If the status code is 200, indicating a successful request, the body of the response will contain the data you requested, e.g. for the credits resource, the full body of the response will look similar to the following XML.
However, a status code that is not 200 means that an error was encountered. In this case the full body of the response will look something like this:
You can see that the XML above contains a list of errors - in this case containing only one entry. The error codes will be specific to the nature of the error. In this case we attempted to access a
resource that doesn't exist. So here the error code is the same as the response header status code 404, meaning 'not found'.
However error codes are sometimes specific to the resource being called.
For example, the sms resource might return errors like this:
In this case, no data was passed to the resource except for the username and password. The errors therefore describe problems with the data passed, like the 'message' parameter being missing.
In other words, any status code that is not 200 indicates an error that you need to investigate. This is most likely to be a mistake in the way that you are making the call, but in rare situations could be an error at the server end. Either way, you should investigate the error before attempting to make the call again.