Response and Error Codes Working with our products

The MTN API returns HTTP status codes in addition to JSON-based error codes and messages.

HTTP Status Codes

The MTN API attempts to return appropriate HTTP status codes for every request. Every response will be mapped to an appropriate HTTP Status Code.

Links

MTN API uses HATEOAS links in the response contents so that the client can easier discover and navigate to the appropriate resource by traversing the hypermedia links.

Errors

Response/Error Code Grouping

The JSON-based response have been grouped, so as to ease identification.

Error Group Error Description Code Range
Customer errors Errors that relate to the Customer/User object, like "User not found", "User ID not found"

0000-1999
Network Errors Errors related to network errors, like "Unreachable" 2000-2999
Server Errors Errors like "path not found", "resource moved" 3000-3999
Authentication Errors like "Access Denied", "Forbidden" 4000-4999
Parameters Errors related to fields or parameters 5000-5999
Billing Billing and Payment related errors like "Insufficient funds" "Billing failed" 6000-6999

Error Messages

MTN API error messages are returned in JSON format. For example, a 404 Not Found error might look like this:

HTTP/1.1 404
Date: Tue, 12 Mar 2019 07:24:54 GMT
Content-Type: application/json;charset=UTF-8
Connection: keep-alive
Set-Cookie: 4e67a54a3d6062c6a5e5c4046646604a=f3fa1a3a190f1bcafbe1c9046fcf4e5f; path=/; HttpOnly
Cache-control: private
{
    "timestamp": "2019-03-12T07:21:07.710+0000",
    "status": 404,
    "error": "Not Found",
    "message": "No message available",
    "path": "/customers/278320123456"
}

Error Codes

When you request a REST-ful API operation that cannot be executed by the MTN API, you get an error code in the response to let you know where the problem lays. Some of these error codes are mapped to standard HTTP status codes. See the table below to learn more about what each error code means and when it is returned. In addition to descriptive error text, error messages contain machine-parsable codes. While the text for an error message may change, the codes will stay the same. The Response/Error Codes are not to be confused with HTTP Status Codes. HTTP Status Codes appear in the HTTP header, while MTN API Error Codes appear in the JSON body, which is why they have been made 4 digits long.

The following table describes the codes which may appear when working with the API. They have been mapped to the HTTP status codes in order to determine the best way to address the issue.

Error Code Error Description HTTP Status code
0000 Success 200
1000 User not found 404
1001 Request error 400
1002 Already subscribed 400
1003 Already un-subscribed 400
1004 Request pending 102
1005 Retry 500
1007 Operation timeout 500
1012 Timeout 408
1013 Request rate exceeded 429
2000 Connection error 400
3000 Service not available 503
3001 System error 500
3003 Timeout 408
3006 Rate exceeded 429
4000 Unauthorised 401
4001 Not allowed 405
5000 Invalid Parameters 400
5001 Request failed 400
6000 Billing failed 403
6001 Insufficient funds 403


For a successful request, the response will contain the requested object. But we differentiate between:##Multi-Status Responses

  1. When the request was successful, but there was no data. If the customer does not have any requested data, then it will be null. E.g. if the customer does not have a MoMo account, then the momo resource object will be null:
"momo": null,
"_links": {
"self": {
  "href": "https://api.mtn.com/v1/customers/2783200000/momo"
}
}

If the customer does not have any location set, then Country and Operator will be null.

"data": {
    "country": "null",
    "operator": "null"
}
  1. Where there was a failure in retrieving some of the data, which is when it wil be a multi-status response. In this case, the client needs to examine the HTTP Status Code, and check the JSON body to determine which part failed. If there was an error retrieving some part of the request, then the HTTP Status Code will be set to 207, and the remaining failed objects will be be excluded. E.g. if there was an error retrieving location, then the data object will be empty, and will not contain Country or Operator properties""data": { }

If all of the service providers are not available, then it will be a multi-status response, containing only some of the requested service providers. In this, the HTTP Status Code will be set to 207, and the systems array will contain an Inactive system. E.g

HTTP/1.1 207
{
    "systemId": "RBT",
    "status": "Inactive",
    "statusCode": 200,
    "message": "Request timed out."
}