Error Handling

• XML validation errors
• Gateway errors
  • 429 errors (GW-0010)
• Business logic errors
  • Authentication of Web Services credentials
  • Authentication of company or console user credentials
  • Function-level 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
• Gateway errors
• Business logic errors
• Mid-process failures

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:

<response>
    <control>
        <status>failure</status>
        <senderid>intacct_dev</senderid>
        <controlid>1662064558</controlid>
        <uniqueid>false</uniqueid>
        <dtdversion>3.0</dtdversion>
    </control>
    <errormessage>
        <error>
            <errorno>XL03000003</errorno>
            <description></description>
            <description2>XML Parse schema error: Fatal Error 76: Opening and ending tag mismatch: delete line 16 and function. Line: 19, column: 18. [Support ID: p5rxS%7EYxEXrDEnVyr0F531W8X9bQAAACQ]</description2>
            <correction></correction>
        </error>

Using an XML validator before submitting requests to the gateway is always recommended.

Gateway errors

Gateway errors can be identified by a GW-nnnn errorno, such as GW-0010. For example:

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <control>
        <status>failure</status>
    </control>
    <errormessage>
        <error>
            <errorno>GW-0011</errorno>
            <description>Invalid Request [Request ID: AC47C2BE:D9EE_63EBC07F.59]</description>
        </error>
    </errormessage>
</response>

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 (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

Invalid Web Services sender ID or password

<response>
    <control>
        <status>failure</status>
        <senderid>myWebSenderId</senderid>
        <controlid>testRequestId</controlid>
        <uniqueid>false</uniqueid>
        <dtdversion>3.0</dtdversion>
    </control>
    <errormessage>
        <error>
            <errorno>XL03000006</errorno>
            <description></description>
            <description2>Incorrect Intacct XML Partner ID or password. [Support ID: sLvU1%7EYxEspDE0Vkv0ago1D_2XqwAAAAM]</description2>
            <correction></correction>
        </error>
    </errormessage>
</response>

Sender ID not authorized for the company:

<response>
    <control>
        <status>success</status>
        <senderid>test_sender_id</senderid>
        <controlid>hello_world</controlid>
        <uniqueid>false</uniqueid>
        <dtdversion>3.0</dtdversion>
    </control>
    <operation>
        <authentication>
            <status>failure</status>
            <userid>test_user_id</userid>
            <companyid>test_company_id</companyid>
        </authentication>
        <errormessage>
            <error>
                <errorno>XL03000006</errorno>
                <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>
            </error>
        </errormessage>
    </operation>
</response>

Authentication of company or console user credentials

Invalid company login credentials:

<response>
    <control>
        <status>success</status>
        <senderid>myWebSenderId</senderid>
        <controlid>testRequestId</controlid>
        <uniqueid>false</uniqueid>
        <dtdversion>3.0</dtdversion>
    </control>
    <operation>
        <authentication>
            <status>failure</status>
            <userid>someUserId</userid>
            <companyid>wrongCompanyId</companyid>
            <locationid></locationid>
        </authentication>
        <errormessage>
            <error>
                <errorno>XL03000006</errorno>
                <description></description>
                <description2>Sign-in information is incorrect</description2>
                <correction></correction>
            </error>
        </errormessage>
    </operation>
</response>

Function-level errors

Invalid object key (recordno)

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

<result>
    <status>failure</status>
    <function>delete</function>
    <controlid>0b554d92-ba94-417b-8d72-81d97e92a953</controlid>
    <errormessage>
        <error>
            <errorno>BL01001973</errorno>
            <description></description>
            <description2>Cannot find vendor with key &#039;12345&#039; to delete. [Support ID: rlf2s%7EYxE1sDE7VRZ0Sar1970ACAAAAAo]</description2>
            <correction></correction>
        </error>
    </errormessage>
</result>

Business rule errors

The following is an example of an error that might be returned based on a business rule:

Mid-process failures

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:

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.

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

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.

Provide feedback