Error Handling

This document presents general recommendations for a basic API implementation and recommended error handling procedures.

Implementation

There are 2 methods of implementing a web service client:

Directly in the client's browser, where calls are made from a loaded web page from a given web server, and call the Engage web services in JavaScript from that web page.
From a server-side script or application that communicates with the Engage SOAP or REST web services endpoints.

Server-side clients

We recommend that you create your web service clients directly on your server, so that:

There is no direct end-user visible information exchange between the browser and the Engage web service: All username and password details will be handled between your server and ours without being exposed publicly.
Data can be queued so you can mark data as being sent successfully and removed from the queue, or rejected, to be retried.
Errors can be logged and reviewed rather than lost
There are no cross-site scripting security restrictions

Running scripts from your server will entail that your page may need to communicate back to your server for example via AJAX that itself will call your web service client or add data into the web service client processing queue, but this is a design implementation question that depends on your specific needs and architecture.

Direct client-side clients from a browser

We do not recommend coding a web service client in JavaScript on a web page for the following reasons:

You cannot hide your username and password that must be sent in clear text to your clients - and this data can then be indexed on Google and made available to the world.
You cannot rely on a 3rd party web browser being able to contact the Engage web service and control the exchange of data from Engage back to the browser and to your server with a 100% success rate
You have limited retry options if you attempt to access the Engage web services when they are not available.
Calls could end up blocking the web page while waiting for data that your application is relying on if there is not sufficient error handling built into the JavaScript web service management code.
You may encounter Cross Site Scripting errors where the browser itself is forbidding your page to make calls to the Engage Webservice

Due to these 5 points above, we do not recommend implementing SOAP or REST web service calls directly within your public web pages that your service to your clients: Some of your calls will be made in "fire-and-forget" mode, meaning that you believe that the web service call has been made, but you have no absolute control on if the call was made, was successful and you have no means of retrying if there was an error that your code could not intercept, or because the page was closed.

Performance Recommendations

If you are planning a mass import of data via the REST or SOAP web service, you should consider using parallelized processing, submitting multiple requests in parallel. This allows calls to be balanced across our API cluster rather than sequentially sent to a single server.

This avoids contention issues where if a call is handled slowly, it does not slow down your overall import process as it would if you were processing the data sequentially. As noted above, you should also have a queuing and logging mechanism to allow retry in case of timeouts or unavailability due to maintenance operations.

Alternative mass import method - Control XML

If you are attempting to mass-import a very large amount of data sequentially, the API methods may not be the most adequate answer, and our Control XML file import method may be better adapted to your needs. After generating a Control XML "capsule" containing processing information and client details, this can be uploaded to an SFTP server, and you can then call a pre-existing Control XML processing task to pick up and import the file via either our SOAP or REST API on an ad-hoc basis or set the processing task to run automatically at a given time.

Handling API responses and overall client execution

Certain API calls as per the documentation may respond with an HTTP 204 response, meaning "successful, but no further response details are required", others will provide you with an HTTP response code indicating success or failure, and can also provide further details in the response body. You should process these responses, especially failure conditions, as the information provided will be very useful in determining the root cause of any problem, and if there is a problem with the submitted API request or a problem with how Mapp is handling the request.

For this reason, we do not recommend creating a "fire-and-forget" API on the assumption that 100% of calls work 100% of the time, as you will have no way of identifying or handling any error conditions.

Due to this, a web service client must check the response of our web service and manage a retry of the call if an error condition is encountered that can be retried.

We also strongly recommend implementing some method to trace the execution of any batch mode API clients, to ensure you can react to any general execution issues in a timely manner, for example, to note if a process is not functioning at all, and to react to any specific processing issues, for example, calls that unexpectedly fail, as per the recommended API Retry Process documented below.

API Retry Process

We recommend the following retry procedures depending on the API used

For API 2.0

Ensure that you have set an adequate timeout for your calls (some calls can return a lot of data and can take more than 30 seconds to respond).
Run initial call
On error: Log that a retry is to be attempted after at least 30 seconds
On subsequent error: Log that a retry is to be attempted after at least 15 minutes
On subsequent error: Log failure and contact Technical Support.

If after the call and 2 retries fail, a definitive failure can be considered, and you should contact Technical Support for further details.

For API 1

Note that API 1 REST and SOAP are deprecated, and we recommend using or migrating to API 2.0 where possible.

Ensure that you have set an adequate timeout for your calls (some calls can return a lot of data and can take more than 30 seconds to respond).
Run initial call
On error:
- Execute a logout API call
- Execute a login API call and get a new token
- Retry call with new connection-token
Log that a retry is to be attempted after at least 30 seconds
On subsequent error: Log that a retry is to be attempted after at least 15 minutes
On subsequent error: Log failure and contact Technical Support.

Response Codes

The API uses HTTP response codes to indicate success or failure. The exact codes depend on the call; the table below lists the common codes and recommended actions.

Code	Status	Description
200	Success	The request succeeded and data on the call is provided in the HTTP body.
204	Success	Everything went well; no response body is returned.
400	Bad Request	The request was malformed or a required parameter was missing or invalid. The response body typically specifies which parameter caused the error (e.g. "Parameter '`XYZID`' is mandatory but no value was specified"). Fix the request and retry.
401	Unauthorized	Add the authorization header.
403	Forbidden	Access error (generally invalid login credentials). Validate user type, username, and password.
404	Page Not Found	Provide a valid URL. Make sure there is no backslash in the URL.
406	Not Acceptable	Validate the "Accept" header.
415	Unsupported Media Type	Validate the "Content-Type" header.
417	Account expired	Try resetting the password or Contact Support.
500	Database Access Limit Exceeded	Reduce the load to ~10 tps (transactions per second) or Contact Support.
5XX	Internal server error	Retry using the API Retry Process above. If the error persists, Contact Support.

CORS is a mechanism for integrating applications with our API. It's an extension of a same-origin policy and is necessary for authorizing resource sharing with external third parties.

If you're having trouble with third-party applications, please contact your Customer Success Manager. We may be able to fix this issue by updating your settings. You will need to specify the (sub)domains in use.

Details to provide Technical Support to aid in any investigation

You may be requested to provide in addition to the calls themselves the following information:

SOAP WSDL URL or REST endpoint
SOAP request and response envelopes for debugging purposes (An envelope is the physical XML data transferred to and from the web service. This generally can be activated in your SOAP client, but the method of activation depends on your programming language)

Documentation Index