I want to create generic response codes, for an API that I am developing. Now I know there are HTTP response codes that are usually recommended to be used, but my API will be handling multiple USSD gateway responses.

So a generalized mapping of response codes within API will highly be useful. After brief Googling I didn't come up with a document or article on best practices while deciding response codes (Whether it should be numeric, alphanumeric, length etc).

Any help or suggestion will highly be appreciated.

  • What does USSD spec tell you? – Arseni Mourzenko Aug 31 '16 at 8:36
  • You mean ISO specs? – FaizanRabbani Aug 31 '16 at 8:58
  • That's what I mean. If there are specific response codes for USSD, they should be in the spec. If not, well, you're on your own, and you should reuse HTTP status codes (and eventually use substatus codes for more details). – Arseni Mourzenko Aug 31 '16 at 9:25
  • I Googled ISO documents, it is precisely known as "ETS 300 957". But couldn't find anything related to response codes. – FaizanRabbani Aug 31 '16 at 9:27
  • From some basic Google research it seems that this is not really a protocol as you know it in terms of an api. It is a session based protocol more like a stream of data. So you open a connection and the start communicating over that session. It's not about requests like a rest api for example. Did you read en.m.wikipedia.org/wiki/USSD_Gateway and eurecom.fr/~dacier/Teaching/Eurecom/Intro_computer_nets/… ? It seems ss7 is the protocol being used. – Luc Franken Aug 31 '16 at 9:56

If HTTP codes are not good enough for you, consider implementing your own. For example, standardize your API response to be something like that:

    "status": "OK",
    "status_message": "Success",
    "meta": {
    "data": {

Let 'status' be an identifier of the response code. 'status_message' - a text description of it.

In case your method executed successfully, return HTTP code 200 + your JSON. In case some error occured, return 400 / 500 HTTP response with your JSON containing your detailed status code and message.

Of course an example above is an example only. It is not meant as a ready-to-use solution.

Keep a documentation with a list of possible response codes from your API. Document each possible response code in a method documentation.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.