SOAP Web Services Reliability Considerations

Issues can arise when SOAP web services operations don't complete or responses aren't received by the client. This topic covers common causes and best practices to help you avoid these issues.

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. If the server receives the request, it will process the operation, even if a disruption occurs later. IThis means the client may not get a response, making it unclear if the operation succeeded or failed.
Error in the NetSuite infrastructure. For example, an application server might fail.
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

Use the following sections for troubleshooting tips and best practices to avoid operation failures.

Client Implementation Considerations and Troubleshooting

Consider using asynchronous request processing for long-running SOAP operations. For more information, see Synchronous Versus Asynchronous Request Processing. The asyncSearch operation can also time out, which may not correspond to the general operation timeout.
Use the SOAP operations search to find and analyze failed 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 fails after a SOAP add or update, the records are still created or updated. Use the internal ID from the SOAP response to prevent duplicate records. Don't resend the SOAP request if the response shows the records were saved. 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. Updating sublist lines in SOAP web services differs between keyed and non-keyed sublists. Keyed sublists allow setting replaceAll to false to update specific lines. Non-keyed sublists ignore replaceAll and must be updated as a whole. For detailed information, see Updating Sublists in SOAP Web Services.

Implementing a Retry Logic

Implement retry logic to resend incomplete SOAP web services requests. A retry mechanism is crucial 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 break 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
                }
            }