Developer ToolsFree calculatorPDF, Excel, Word exportNetSuiteAll NetSuite tools

NetSuite RESTlet Batch Size Calculator: Governance, Payload and Timeout

This calculator finds the largest batch a NetSuite RESTlet can process per call without hitting SSS_USAGE_LIMIT_EXCEEDED, SSS_TIME_LIMIT_EXCEEDED or the payload limit, and estimates how long a full load takes at your concurrency. It sizes batches; for totalling the units in a script, use the governance estimator.

Your numbers

Usage units per record

units

For example a transaction record.load (10) plus save (20).

Fixed units per call

units

Lookups and searches done once per call.

Payload per record

Seconds per record

Measure from the execution log of a test call.

Time budget per call

240 s

Keep below the 300 second RESTlet limit.

Share of unit and payload limits to use

80 %

Records to process

records

Parallel calls available to this integration

calls

Your results

Safe batch size per call

132

Estimated wall-clock time

66.9 min

Calls run in waves of the concurrency you set.

Max records by usage units

132

Max records by 10 MB string limit

2,048

Max records by time budget

600

RESTlet calls needed

379

Limits from Oracle help: 5,000 usage units per RESTlet script execution, 10 MB guaranteed per input or output string, 300 seconds execution time. Per-record costs and timings must be measured in your account.

Save results:

Batch size vs usage units per record

Sweeps Usage units per record from 5 to 100, holding your other inputs fixed.

Get your RESTlet load profile checked

Send the per-record operations and a sample payload and we will return a batch size, retry design and concurrency plan for your account.

Optional. The tool and every export work without this. No spam.

Was this tool useful?

How to use it

Work out the usage units per record from the calls your RESTlet makes per record: Oracle's governance tables give the cost per API by record class, for example record.load and record.save on a transaction. Add one-time units per call for searches or lookups. Estimate payload per record from a sample JSON body, and measure seconds per record by running a test batch and reading the start and end of the execution log. Set the safety share to leave headroom for heavier records. The tool returns three caps and uses the smallest, then the number of calls and wall time for your concurrency.

Return per-record success and error in the response so a partial failure does not force a full retry.
Use an idempotency key such as externalid so retries after a timeout do not create duplicates.

The limits behind the formula

Oracle help states that RESTlets can use up to 5,000 usage units per script execution, that RESTlet input or output is guaranteed up to 10 MB per string, and that the RESTlet script type has a 300 second execution time limit, after which NetSuite throws SSS_TIME_LIMIT_EXCEEDED. Concurrency is governed per account and counts RESTlet and web services requests together, so a middleware running 5 parallel calls competes with every other integration on the account; exceeding it returns SSS_REQUEST_LIMIT_EXCEEDED or HTTP 429.

by_governance = floor((5000 x share - fixed units) / units per record)
by_payload = floor(10,240 KB x share / KB per record)
by_time = floor(time budget / seconds per record)

Worked example

Defaults: 30 units per record, 20 fixed, 4 KB, 0.4 s, 240 s budget, 80% share. Governance allows floor((4,000 - 20) / 30) = 132 records, payload allows 2,048 and time allows 600, so usage units decide: 132 records per call. 50,000 records need 379 calls; at 5 in parallel that is 76 waves of about 53 seconds, roughly 67 minutes. If the RESTlet switches to record.submitFields for updates, units per record drop and time becomes the limit, which the chart shows as the curve flattening.

Gotchas

A client-side timeout shorter than the server's lets the RESTlet keep running after the caller gives up, so the caller retries and creates duplicates; set the client timeout above your time budget. User event scripts and workflows on the records you save run inside the same request and consume time, which is why measured seconds per record matter more than API costs. If a batch regularly needs more than one call's worth of units, hand the work to a map/reduce script: the RESTlet accepts the payload, stores it, and queues the task.

Frequently Asked Questions

What is the NetSuite RESTlet timeout?

Oracle help lists a 300 second execution time limit for the RESTlet script type. When a call runs longer NetSuite throws SSS_TIME_LIMIT_EXCEEDED. Keep batches well under it, for example a 240 second budget, because records with heavy user event scripts take longer than test records.

How many governance units does a RESTlet get?

5,000 usage units per script execution, five times the 1,000 units of a Suitelet or user event script. Usage is also tracked at the API level, where each call such as record.load, record.save or search.run has its own cost that depends on the record type.

What are the NetSuite API rate limits for RESTlets?

RESTlets are limited by concurrency rather than a per-minute rate. The account concurrency limit depends on service tier and SuiteCloud Plus licences and is shared between RESTlets, REST web services and SOAP. Requests beyond it are rejected, so integrations should queue and back off rather than retry immediately.

How large can a RESTlet request body be?

Oracle help guarantees up to 10 MB per string for RESTlet input or output, noting larger outputs sometimes work but 10 MB is the official figure. JSON bodies grow quickly with line-level data, so size batches from a real sample rather than field counts.

If you want your integration team to ask NetSuite which batches failed and why in plain English, with answers drawn from execution logs on your own infrastructure, we can set that up.

Talk to an Expert Explore More Free Tools