SOAP Web Services Warnings, Errors, and Faults

Based on the error code or fault that is received, the client can take the appropriate action.

Warnings: informational notifications requiring an action within the UI but requiring no response from a Web service call. Data may or may not be processed depending on preference settings. For more information about preferences, see Company-Wide Preferences.
Errors: exceptions returned on a record-by-record basis due to invalid or incomplete data. The service is processed as requested, however, only those records without errors are updated.
Faults: a fundamental exception type that results in the entire request not being processed.

Warnings

A warning is a notification sent to a user to prevent a subsequent error or to ensure better data quality. In the NetSuite UI, a warning is presented to the user through a popup window and generally requires an action from the user. Since there is no interaction of this nature in the SOAP web services model, the request must specify what to do in the case of a warning. The options are:

Ignore the warning and submit the record to the database
Heed the warning and abort the submission — treat as an error

You can set a company wide preference on the SOAP Web Services Preferences page on how to handle warnings or you can specify how warnings should be handled in a specific request. Request level preferences override company-wide preferences. Refer to Company-Wide Preferences for information about how to set company-wide preferences.

Following is an example of a warning message in the response to a request to add a customer record without a zip code (with the Treat Warnings as Errors preference set to false):

Code

          <addResponse xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
   <writeResponse> 
      <platformCore:status isSuccess="true" xmlns:platformCore="urn:core.platform_2017.1.platform.webservices.netsuite.com">
         <platformCore:statusDetail type="WARN">
            <platformCore:code>WARNING</platformCore:code>
         <platformCore:message>Without a zip/postal code it will not be possible to use
          this address with 3rd Party shippers. Click Cancel to edit the address.
         </platformCore:message>
         </platformCore:statusDetail>
      </platformCore:status>
      <baseRef internalId="50" type="customer" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core.platform_2017.1.platform.webservices.netsuite.com"/>
   </writeResponse>
</addResponse>

The above customer was added because no error occurred. However, future errors could be avoided by responding appropriately to the warning message.

For a detailed list of all warning messages and the associated codes generated by NetSuite, see Warning Status Codes.

Errors

Errors result if invalid or incomplete data is submitted when performing an operation. For example, if a client attempts to update a customer record with an invalid internal ID, the operation fails and the response contains an error code and message.

When numerous records are submitted within the same request, each is treated individually. For example, if a client attempts to update two events within the same request, where one record has invalid data and the other has valid data, only one of the records has an error and is not updated.

Code

          <updateListResponse xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
   <writeResponseList>
      <platformCore:status isSuccess="true" xmlns:platformCore="urn:core.platform_2017_1.platform.webservices.netsuite.com"/>      
      <writeResponse> 
         <platformCore:status isSuccess="false" xmlns:platformCore="urn:core.platform_2017_1.platform.webservices.netsuite.com">
            <platformCore:statusDetail type="ERROR">
               <platformCore:code>RCRD_DSNT_EXIST</platformCore:code>
               <platformCore:message>That record does not exist. Invalid record:type=event,id=222,scompid=3604360</platformCore:message>         
            </platformCore:statusDetail> 
         </platformCore:status>
         <baseRef internalId="222" type="calendarEvent" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core.platform_2017_1.platform.webservices.netsuite.com"/>
      </writeResonse>
      <writeResponse>
         <platformCore:status isSuccess="true" xmlns:platformCore="urn:core.platform_2017_1.platform.webservices.netsuite.com"/>
         <baseRef internalId="220" type="calendarEvent" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core.platform_2017_1.platform.webservices.netsuite.com"/>
      </writeResponse>
   </writeResponseList>    
</updateListResponse>

For a detailed list of all error messages and the associated codes, see Error Status Codes.

Error Reporting for afterSubmit Script Failures

When an afterSubmit script runs after a SOAP web services add or update request, and the script fails, the records are still created or updated in NetSuite. The SOAP response indicates that the record has been created or updated even if an afterSubmit script that runs after the SOAP web services request fails.

Using the internal ID of the record, available in the SOAP response, you can avoid creating duplicate records. If the SOAP response indicates that the records have been saved, you only need to retry the user event script. You should not send the SOAP web services request again.

For information about working with afterSubmit scripts, see afterSubmit(context) and SuiteScript 2.x User Event Script Type.

The following is an example of the error message in the SOAP response.

          <?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<platformMsgs:documentInfo xmlns:platformMsgs="urn:messages_2017_1.platform.webservices.netsuite.com">
<platformMsgs:nsId>WEBSERVICES_3604360_042020171945139757546407083_e2869fb06ef3</platformMsgs:nsId>
</platformMsgs:documentInfo>
</soapenv:Header>
<soapenv:Body>
<addResponse xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<writeResponse>
<platformCore:status isSuccess="false" xmlns:platformCore="urn:core_2017_1.platform.webservices.netsuite.com">
<platformCore:statusDetail type="ERROR">
<platformCore:aftersubmitFailed>true</platformCore:aftersubmitFailed><platformCore:code>USER_ERROR</platformCore:code>
<platformCore:message>Please enter value(s) for: Company Name, Subsidiary</platformCore:message>
</platformCore:statusDetail>
</platformCore:status>
<baseRef internalId="68" externalId="EID_PO_68" type="purchaseOrder" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core_2017_1.platform.webservices.netsuite.com"/>
</writeResponse>
</addResponse>
</soapenv:Body>
</soapenv:Envelope>

Faults

Faults are exceptions that are of a more fundamental nature than errors. A key distinction between errors and faults is that a fault prevents any operation within a request from being processed whereas an error prevents only a single operation from succeeding on an individual record.

For example, continuing from the case above, if the user's session has timed out when making the request, neither update for either event record is processed and an invalidSessionFault is returned in the response.

Expand code

          <soapenv:Fault>
   <faultcode>soapenv:Server.userException</faultcode>
   <faultstring>Your connection has timed out. Please log in again.
   </faultstring>
   <detail>
      <platformFaults:invalidSessionFault xmlns="urn:faults.platform_2017_1.platform.webservices.netsuite.com">
         <platformFaults:code>INVALID_SESSION</platformFaults:code>
         <platformFaults:message>Your connection has timed out. Please log in again.</platformFaults:message>
      </platformFaults:invalidSessionFault>
      <ns1:hostname xmlns:ns1="http://xml.apache.org/axis">partners-java10009.bos.netsuite.com
      </ns1:hostname>
   </detail>
</soapenv:Fault>

SOAP uses the detail element to capture the error code through the code element and the error message through the message element. The faultcode and faultstring are automatically populated by the server.

Following is an example of a SOAP fault named InvalidCredentialsFault for an invalid e-mail address that is returned as part of the login operation.

Code

          <soapenv:Fault>
      <faultcode>soapenv:Server.userExveption</faultcode>
      <faultstring>You have entered an invalid e-mail address or account number. Please try again.</faultstring>
      <detail>
         <platformFaults:invalidCredentialsFault xmlns="urn:faults.platform_2017_1.platform.webservices.netsuite.com">
            <platformFaults:code>INVALID_LOGIN_CREDENTIALS</platformFaults:code>
            <platformFaults:message>You have entered an invalid e-mail address or account number. Please try again.</platformFaults:message>
         </platformFaults:invalidCredentialsFault>
         <ns1:hostname xmlns:ns1="http://xml.apache.org/axis">partners-java10009.bos.netsuite.com
      </ns1:hostname>
   </detail>
</soapenv:Fault>

For a detailed list of fault messages and the associated codes, see SOAP Fault Status Codes. The list does not contain every SOAP fault status code. Some SOAP faults do not have a special fault code.

Important:

Unexpected errors return an error ID that can be provided to NetSuite Customer Support to help them isolate the error in your account. The following is an example of the error ID:

                <platformCore:code>UNEXPECTED_ERROR</platformCore:code>
      <platformCore:message>An unexpected error occurred. Error ID: fevsjhv41tji2juy3le73</platformCore:message>

Error IDs will be especially helpful for async operations, as the ID will indicate the error that occurred during the execution of the job, not the retrieval. The exception is if the async error occurred at the platform-level. In this case, the stack will be attached to the job itself.

Warnings

Code

Errors

Code

Error Reporting for afterSubmit Script Failures

Faults

Expand code

Code

Related Topics