Although you’ve carefully crafted your Mautive application to flow smoothly, it’s hard to know exactly when an unforeseen error will occur, which can possibly break your script and cost you time and money.
Our API attempts to provide basic information on any errors or problems that happened during a request. There’s typically two types of errors that can occur with an API request:
- Service level
- Application level
We strive for the highest uptime possible, but even we sometimes experience service disruptions that involve anything from code issues to server-level or network problems. Service level errors involve anything from network requests timing out to the service being unavailable, or even raw errors printing out. You may receive an indecipherable response, or possibly no response at all! In these cases the issue is always resolved on our end in a timely manner. Your Mautive application could attempt to detect these types of errors, but since it’s hard to predict exactly what (and how) things will be returned (if anything is returned in the first place) your only real action is to inform your users of the Mautive service disruption and to monitor updates through our available incident channels.
Application level errors are clean, graceful error messages returned from the Mautive application, and almost always indicate improper usage, such as attempting to load a contact that doesn’t exist or passing an invalid API key. Application level errors are less severe than service level errors, and will always provide a human-readable error message that can be expected in the same format. These errors usually have to be fixed by the API developer (the external application using the Mautive API), as opposed to the actual creators of the Mautive service (us).
When using the API, think of Mautive as your driver. When you make an API request, you are essentially telling Mautive to route you to your intended destination or goal (such as finding a campaign report, or adding a contact). If Mautive can route you to your destination, it’s considered a successful request. If not, it will try to tell you why (such as a roadblock that occurred during the drive).
Let’s look at an example request for a user’s details:
https://ACCOUNT.api-us1.com/admin/api.php ?api_key=fca40895042f8b0e7...dcd830e82802d85838cbc8a8b &api_action=user_view &api_output=json &id=1
Assuming the above request does not experience a service level error, Mautive will attempt to look up the user with ID 1 for the associated account. If found, their data is returned along with some fixed keys that tell you a little about your request:
{
"id": "1",
"username": "admin",
"first_name": "Test",
"last_name": "Test",
"email": "[email protected]",
"last_login": "2013-09-12 07:13:46",
"sourceid": "0",
"sourceupdated": null,
"productset": null,
"a_now": "2013-09-12 09:39:22",
"groups": "3",
"result_code": 1,
"result_message": "Success: Something is returned",
"result_output": "json"
}
If the request was successful (meaning Mautive was able to get you to your destination), you’ll see a result_code being set to 1. The result_message will also provide a generic positive message such as "Success: Something is returned".
The HTTP response code should also be 200 in this case.
Now let’s try to load a contact using an ID that doesn’t exist:
https://ACCOUNT.api-us1.com/admin/api.php
?api_key=fca40895042f8b0e7...dcd830e82802d85838cbc8a8b
&api_action=user_view
&api_output=json
&id=999999999
If the request was not successful, result_code will be 0 and result_message will provide a description of what went wrong.
{
"result_code": 0,
"result_message": "Failed: Nothing is returned",
"result_output": "json"
}
In this case the HTTP response code will be 404.
Our PHP API wrapper will also include an alternative success key (returns 1 or 0), also an error key which provides the error message if success is 0, or empty if success is 1. There will also be a http_code that returns the HTTP status code of the request (almost always 200 unless something went wrong).
{
"result_code": 0,
"result_message": "Failed: Nothing is returned",
"result_output": "json",
"success": 0,
"error": "Failed: Nothing is returned",
"http_code": 404
}
The important thing to take away is that both of the above requests are considered successful on the service level, but one of them failed on the application level.
Your Mautive applications can capture these errors and proceed gracefully in order to avoid disrupting the user with a broken application.
Using our PHP wrapper, your code flow could go something like this:
$response = $ac->api("user/view?id=1");
if ((int)$response->success) {
// successful response - continue as planned.
}
else {
// error occurred - provide the user some information.
echo "We're sorry! Your request failed with the following error: " . $response->error;
echo " (HTTP code " . $response->http_code . ").";
}
As always, let us know of any questions or concerns you may have!
