SOAP Web Services Reliability Considerations

You may encounter issues when a SOAP web services operation does not complete or the client does not receive a response. This topic provides the most common causes of this issue and provides best practices to help you avoid them.

Reasons for SOAP Web Services Operation Failures

Network connection errors at any point of the connection or minor network disruptions and timeouts.Such disruptions can occur anytime. Note that if the server receives the request, the processing of operations continues, even if a network disruption occurs later. In such a case, it is possible that the client does not receive a response from the server, so it is not clear for the client whether the operation completed successfully or failed.
Error in the NetSuite infrastructure. For example, an application server might crash.
Application server restart due to a hot-fix, system maintenance, or upgrade.
Client error. Due to such errors, the client might not receive a response from the server, and cannot assess whether the operation succeeded or failed.
Exceeding a timeout:
- Web services sessions automatically time out after 20 minutes of inactivity, requiring a login to resume activity.
- If a web services request takes more than 15 minutes to complete, it automatically times out.

Important:

List and search requests that take longer than 15 minutes to process are terminated. For more information about handling long-running list and search operations, see Handling of Lengthy Requests.

Best Practices and Troubleshooting

The following sections provide suggested actions for troubleshooting, and best practices for avoiding issues with operation failures.

Client Implementation Considerations and Troubleshooting

For long-running SOAP web services operations, consider using asynchronous request processing. For more information, see Synchronous Versus Asynchronous Request Processing. Note that the asyncSearch operation can also time out, and this timeout does not necessarily correspond to the general operation timeout.
Use the SOAP web services operations search to search for and analyze information about failing SOAP web services requests and operations. For more information, see SOAP Web Services Operations Search Type.
Check the SOAP web services usage log for information about the operation and the status of the request. For more information, see Using the SOAP Web Services Usage Log.
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. 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 should not send the SOAP web services request again. For more information, see SOAP Web Services Warnings, Errors, and Faults.

Synchronous Client Implementation

To prevent duplicate records and to make sure that all records are correctly added, use external IDs and the upsert and upsertList operations to update records in NetSuite.

Note:
External IDs originally serve to identify records in a third party system. If you cannot use such an identification, generate a random but unique external ID, for example, a UUID, which you can then use to create records in NetSuite.
You must implement your business logic in a way that your update operation is idempotent.

Idempotency is also necessary for working with sublists. When you work with sublists in SOAP web services, the approach for updating sublist lines varies depending on whether you are working with keyed sublists or non-keyed sublists. Keyed sublists allow you to set the replaceAll attribute to false, to update only the specific lines you submit in your requests. For non-keyed sublists, the replaceAll attribute is ignored, and you must interact with the sublist as a whole. For detailed information, see Updating Sublists in SOAP Web Services.

Implementing a Retry Logic

You must implement a retry logic to resend SOAP web services requests that do not complete. Using a retry mechanism is essential for the following reasons:

To make sure that requests that fail due to timeout issues are executed again.

Note:
If a request times out and you send a retry request, it is possible that the response contains fewer records than the first response.
To make sure that requests rejected due to concurrency violations are executed again. For information about concurrent sessions, see Web Services and RESTlet Concurrency Governance.
To make sure that you do not violate SOAP web services session management timeouts and limits. For more information, see Session Management for SOAP Web Services.

See the sample retry code below for an example.

Sample Retry Code

                        int i = 0;
            int maxAttempts = 5; // try it 5 times, then fail for good
while (i < maxAttempts)
            {
                response = doWSCall();
                isSuccess = response.getIsSuccess();
                errorMsg = response.getErrorMsg();
if (isSuccess == false && (errorMsg == WS_CONCUR_SESSION_DISALLWD || errorMsg == WS_REQUEST_BLOCKED))
                {
                    wait();
                    i++; // try again
                }
                else 
                {
                    break; // end the cycle
                }
            }