Upcoming NetSuite Governance Changes Limit REST Integrations

Starting in 2017.2, NetSuite began introducing a service release which places definitive limits on REST integrations. NetSuite is introducing this change in order to provide better overall system stability and performance in a shared tenant cloud environment. However, this change may impact customers whose system design currently includes REST interfaces. System performance may degrade as a result of more dropped requests during peak periods.

NetSuite currently offers two web service interfaces in order to communicate with other external applications and systems, namely REST (RESTlets), SOAP (SuiteTalk), you could argue that a public Suitelet is a third option, however we will take this off the table because it does not offer authentication and is insecure. There are many aspects to consider when determining which web-service option to leverage for a given integration project. Some of the biggest factors to consider are how many user licenses are required (cost) to connect to NetSuite, the rate of transactions in a given time period, what interfaces are supported by the third-party application, and performance considerations particularly for real-time integration requirements. The following lists highlights the different attributes to consider when making a technology selection.

SuiteTalk (SOAP)

• Heavy
• Stateful
• WSDL (Schema) provided by NetSuite
• XML over HTTP
• No concurrent calls unless you buy a SuiteCloud Plus License. If you buy you one license then you get 10 concurrent sessions per user, a second one gets you 20 concurrent sessions per user (2 web service users), and three gets you 3 web service users supporting up to 30 sessions
• One user assigned and can have 10 sessions per SuiteCloud Plus license

RESTlets

• Light
• Stateless
• The format of the message payload needs to be defined
• JSON over HTTP
• RESTlets can support up to 10 concurrent connections from a single user login (up until 7/21/2016)

Currently, RESTlet scalability was determined by how many users you had allocated and was easily increased by simply adding more users. Each new user would allow for 10 connections (up to 50 unofficially as a maximum) supplying an easy and understandable way to scale an integration at launch and as these integrations grew. We have observed in practice that RESTlets perform at about 8X as fast as SuiteTalk and allowed for more flexibility in developing custom integrations to NetSuite. Due to the added cost and relatively slow performance and flexibility afforded by SuiteTalk, most of the time REST would be the clear choice over SOAP.

Over the past few years since introduced, REST has taken hold as the leading web service option. Customers may now be surprised to learn that NetSuite is now providing definitive guidance on governance limits on RESTlets limiting concurrency by account instead of by user. This change impacts both SuiteScript 1.0 and 2.0 RESTlets. NetSuite claims that this limit is not a hard limit currently, but is not reliable for any development and seems more as a way to allow for transitions to other options. NetSuite recommend a maximum of 25 concurrent threads per account. If customers exceed the recommended number of threads, NetSuite will allow it if they have capacity at the time of execution. Going over this limit will yield an HTTP 400 response if there is no capacity:

• HTTP status code 400 Bad Request signalizing that server will not process the client request.
• SuiteScript SSS_REQUEST_LIMIT_EXCEEDED error.

What this means for Customers:

If you have REST integrations, you may need to handle the new error and retry accordingly. It is recommended that you record the frequency of your RESTlet requests. Ideally, there is a middleware integration layer in place that can handle this automatically error handling and auditing. Your third-party applications may need to handle the overflow of failed requests with the SSS_REQUEST_LIMIT_EXCEEDED error thrown and retry again after a delay until the request gets to NetSuite. This may or may not require code changes to the applications or middleware sending requests into NetSuite RESTlets. If you have many clients connecting via REST which would exceed this limit, you would almost certainly need to redesign your solution to use a message-broker middleware approach which can multiplex many requests into a single connection or use an exponential back-off algorithm similar to TCP/IP to throttle the number of requests based on contention.

What this means for NetSuite Developers:

With a system-wide maximum this requires an integration design to take a holistic view of the system and all the RESTlet interfaces before adding new REST interfaces. Moreover, we may start to see the need for more middleware to queue up multiple individual requests into NetSuite and instead send them in bulk using a single connection instead of a new connection for each request. Designers will also need to think about finding a way to skinny down the logic in their RESTlets and perform additional logic in other script types, or potentially a mixed-use of SOAP for simple record actions and RESTlets for more complex integration flows. In some cases, customers may need to redesign their integrations to increase responsiveness and reduce the number of failed messages due to this new restriction in RESTlet governance.

If you’re uncertain about how this change impacts your organization, or how to remediate the impacts, our technical experts are available for consultation should you have any questions.

Update 7/17/2016:

Original date for this update was scheduled to be effective July 21st, 2016, but new information indicates that it will be delayed until a future patch/release.

Update 8/27/2017:

NetSuite has finally provided the conclusive REST limitations as part of the 2017.2 Release.  We should note that the new changes do severely limit the throughput for REST integrations, however the new model does allow for customers to pay for increased throughput by purchasing additional SuiteCloud Plus licenses.  The following excepert is from the 2017.2 Release Notes which describes the new limitations for REST integrations:

Changes in Web Services and RESTlet Concurrency Governance
In previous releases of NetSuite, concurrency for web services and RESTlets was governed separately
per user and authentication method. NetSuite 2017.2 includes changes to concurrency governance. As
of this release, web services and RESTlet concurrency is additionally governed per account. The new
account governance limit applies to the combined total of web services and RESTlet requests.

Timing of the Change
The timing of the change is different for different account types.
The change is enforced in all 2017.2 release preview accounts and in all development accounts, as of
the 2017.2 upgrade.
The change is enforced for most production and sandbox accounts as of the 2017.2 upgrade. For a
subset of accounts that we have determined may be potentially affected by this change, the change
to concurrency governance is not tied to the 2017.2 upgrade. For these accounts, administrators will
receive separate communications with details about the timing of the change.

Details of the Change
The account governance limit for concurrent requests is based on the service tier and the number of
SuiteCloud Plus licenses available for your production, sandbox, and release preview accounts. The
base limit is increased by 10 for each SuiteCloud Plus license. For development and partner accounts,
the base limit is always five.

For example, if you are on Service Tier 1 and you have five SuiteCloud Plus licenses, the limit for
concurrent requests in your production account is 65 (15+5*10). If you are on shared service with one
SuiteCloud Plus license, your account limit is 15 (5+10).

In web services that use the login and logout operations or request-level credentials for authentication, the existing governance limits per user are kept. For web services with token-based authentication (TBA) and for RESTlets, there are no per-user limits for concurrent requests. The change in governance may provide increased concurrency for web services integrations that use TBA. This change provides more limits on RESTlet integrations, which are capped at the maximum concurrency defined for an account.

Note: For sessions authenticated with Outbound Single Sign-on (SuiteSignOn), concurrency is
governed per user and additionally per account.

If you exceed the limit for concurrent requests, an error is thrown. RESTlet and web services requests
that are rejected because an account has exceeded the concurrency governance limit result in one of
the following server responses.

For RESTlet requests, the following errors occur:
■ HTTP error code: 400 Bad Request
■ SuiteScript error code: SSS_REQUEST_LIMIT_EXCEEDED

For web services requests, the following SOAP faults occur:
■ ExceededConcurrentRequestLimitFault
■ ExceededRequestLimitFault

Recommended Actions
Review your client applications to ensure they can handle the error codes.
Upgrade your client applications to serialize your requests, or to try sending a request later if the client
application receives the WS_CONCUR_SESSION_DISALLOWED response.

Update 7/24/2019:

This blog is no longer accurate with the latest changes to NetSuite Integrations and should be referenced purely for historical purposes.