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"
}

2. 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."
}