Error handling within the Web Services Gateway includes multiple layers.

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 (control, authentication, or content) and provides detailed information about the cause in a subsequent errormessage element.

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:

XML error response for invalid Web Services credentials

The following is returned when the sender ID is not authorized for the company:

                <description>Invalid Web Services Authorization</description>
                <description2>The sender ID &#039;test_sender_id&#039; is not authorized to make Web Services requests to company ID &#039;test_company_id&#039;.</description2>
                <correction>Contact the company administrator to grant Web Services authorization to this sender ID.</correction>

Authentication of company or console user credentials

The following is returned for invalid company login credentials:

XML error response for invalid company credentials

Function-level errors

The following is returned after an attempt to delete a vendor object using an invalid key:

XML error response for delete with invalid key

The following is returned based on a business rule:

XML error response for business rule

Mid-process failures

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 might 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:

  1. Always provide a unique value such as a GUID, timestamp, or sequenced number for each function element’s controlid attribute, for example:

    <function controlid="x99876">

    The system logs the controlid of each function request when it is processed.

  2. On encountering a mid-process failure (no response from the gateway), resubmit the original request with the uniqueid in the control element set to true.

       . . . 

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.

The <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.

control ID for the request versus control IDs for functions

Provide feedback