- XML validation errors
- Gateway errors
- Business logic errors
- Mid-process failures
- Control ID for a request versus control ID attribute of a function
There are several different categories of errors that your client application needs to handle when using the Web Services API.
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, the
<control> section of the response will show the status as “failure” and the
<errormessage> section will contain details of the problem. For example:
Using an XML validator before submitting requests to the gateway is always recommended.
Gateway errors can be identified by a
GW-nnnn errorno, such as
GW-0010. For example:
429 errors (GW-0010)
Sage enforces rate limiting to ensure that all API requests can be processed according to their contracted levels of service. A 429 error indicates that your API client has hit its assigned rate limit by submitting too many requests in a short period of time. This could happen for several reasons, such as:
- The client makes frequent “polling” requests to check for changes.
- The client uses a loop that causes it to make frequent or concurrent requests.
- The contracted level of service is not adequate for the needs of the client application.
Here are some suggestions for avoiding and responding to 429 errors:
- Implement a backoff mechanism to reduce 429 occurrences and a retry mechanism to ensure that requests are retried until they are successful.
- Consult with Sage Intacct to find better ways to be alerted about data changes other than polling.
- If your application requires it, upgrade to a level of service that allows for more requests.
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
Invalid Web Services sender ID or password
Sender ID not authorized for the company:
Authentication of company or console user credentials
Invalid company login credentials:
Invalid object key (recordno)
The following is returned after an attempt to delete a vendor object using an invalid key:
Business rule errors
The following is an example of an error that might be returned based on a business rule:
A mid-process failure is a 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:
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.