Error handling within the Sage Intacct Web Services Gateway includes multiple layers:
- XML validation errors
- Business logic errors
- Mid-process failures
- Control ID for a request versus control ID attribute of a function
XML validation errors
Before any other checks are performed, the XML request is validated to ensure that the XML is well formed. If the XML has syntax errors, an XML response is not returned. Instead, parser errors are returned directly in the HTTP connection.
Using an XML validator before submitting requests to the gateway is always recommended.
Business logic errors
This category of errors includes any issues with the data provided in the
request. This can be issues with the Web Services credentials, issues with the company credentials, improper use of API function calls, and so forth.
When such errors are encountered, the XML
response from the gateway shows a failure status within the problematic element (
content) and provides detailed information about the cause in a subsequent
If the error occurs at the control level, no operations are executed. If the error occurs at the authentication level, no function calls are executed. If the error occurs at the content level, only the problematic function call fails, other function calls can succeed.
The following are examples of errors that might be returned in a response.
Authentication of Web Services credentials
The following is returned for an invalid Web Services sender ID or password.
Authentication of company or console user credentials
The following is returned for invalid company login credentials.
The following is returned after an attempt to delete a vendor object using an invalid key.
The following is returned based on a business rule.
A mid-process failure is a catastrophic hardware, network, software, or other failure that prematurely terminates request processing at the gateway. When this happens, no XML response is provided from the gateway and you may receive an HTTP error code such as a 500 server error.
Depending on the nature of your request and the timing of the mid-process failure, all or part of the request can remain unprocessed. For example, a request with ten function calls might encounter a failure after the first five are processed. In this case, you need to resubmit the request so that the last five function calls can be processed. Of course, the system needs a way to determine which functions have been processed and which have not—this is why your request should always provide unique identifiers for function calls.
Note: Be aware that you can encounter the lack of an XML response if you submit a particularly long request that causes a timeout. The difference here is that the processing will still be completed by the Sage Intacct system. It is recommended that you manage the size and duration of your requests to avoid timeouts whenever possible.
To handle mid-process failures:
Always provide a unique value such as a GUID, timestamp, or sequenced number for each function element’s
controlidattribute, for example:
The system logs the
controlidof each function request when it is processed.
On encountering a mid-process failure (no response from the gateway), resubmit the original request with the
controlelement set to
<control> <senderid>myWebSenderId</senderid> <password>****</password> <controlid>7a4ce54d-63d4-4433-bf09-92fcb00bab8d</controlid> <uniqueid>true</uniqueid> . . .
This setting tells the system to check whether functions have already been processed before firing them. The system compares the function control IDs in the resubmitted request against previously cached requests and activity logs to ensure that each function is executed only once.
Control ID for a request versus control ID attribute of a function
Keep in mind that there are two places in a request where control IDs are used, and they serve different purposes.
<controlid> element in the
<control> block is simply used by a client to match a request with a response. The
controlid attribute of a
<function> element is required for uniquely identifying functions for recovery purposes.