When you make a request to the API, it will respond like a normal HTTP r=
esponse.
Your programming language will probably provide an easy way =
to parse the response, however it could be useful to understand how the res=
ponse is constructed.
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 s=
tatus 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 cod=
es is found below.
Status Code |
Meaning |
|---|---|
| 200 | OK. We were able to successfully execute the = requested operation. |
| 400 | Bad request. There was a problem with your re= quest data, see the status message for details. |
| 403 | Incorrect username/password, or you do not ha= ve sufficient rights to access the specife resource. |
| 404 | The specified resource could not be found. |
| 405 | The specified method (GET, POST, PUT or DELET= E) is not available for this resource. |
| 500 | An unexpected error occurred |
| 501 | The method requested has not been implemented. |
| 503 | Service Unavailable. The Web Se= rvice 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: =E2=80=9CYour 201 reques= ts exceed the maximum allowed of 100 requests within 15 minute(s). Please t= ry again later=E2=80=9D. 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, su= ch 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 reso= urce, the full body of the response will look similar to the following XML.=
<?xml version=3D"1.0" encoding=3D"ISO-8859-1"?&= gt; <!DOCTYPE response PUBLIC "-//textmarketer.biz//DTD Web Services REST 1.2//EN" "http://api.textmarketer.co.uk/services/rest/DTD/credits_get.dtd"= > <response processed_date=3D"2011-04-12T14:00:09+01:00"> <credits>450</credits> </response>=20
However, a status code that is not 200 means that an error was encounter= ed. In this case the full body of the response will look something like thi= s:
<?xml version=3D"1.0" encoding=3D"ISO-8859-1"?= > <!DOCTYPE response PUBLIC "-//textmarketer.biz//DTD Web Services REST 1.2//EN" "http://api.textmarketer.co.uk/services/rest/DTD/errors.dtd"> <response processed_date=3D"2011-04-12T14:02:00+01:00"> <errors> =09<error code=3D"404">Not Found (ERR255)</error> </errors> </response>=20
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 o=
f the error. In this case we attempted to access a
resource that does=
n'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 spe=
cific to the resource being called.
For example, the sms resource might return errors like this:
<?xml version=3D"1.0" encoding=3D"ISO-8859-1"?&= gt; <!DOCTYPE response PUBLIC "-//textmarketer.biz//DTD Web Services REST 1.2//EN" "http://api.textmarketer.co.uk/services/rest/DTD/errors.dtd"> <response processed_date=3D"2011-04-12T14:12:04+01:00"> <errors> =09<error code=3D"10">invalid number or not an integer</= error> =09<error code=3D"9">invalid number or too short</error&= gt; =09<error code=3D"7">invalid message or missing</error&g= t; =09<error code=3D"4">invalid originator or missing</erro= r> </errors> </response>=20
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 tha= t 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.
The exact error codes are specific to the resource, you can see it here.
If after investigation you are unable to determine the cause of the erro= r, please contact Text Marketer.