← Acumatica integration

The API budget

The constraint on an Acumatica instance is not one number. A licence caps three separate things, and confusing them is why integrations get blamed for problems they did not cause. All three are visible to the customer on License Monitoring Console (SM604000), on the License tab.

A trial licence caps API users at two and imposes no other limits.

The one that surprises people: silent delay

Once the past minute's traffic reaches 50% of the per-minute limit, the server starts delaying each request rather than refusing it. The delay is computed as remaining time in the minute divided by remaining request budget — so it degrades gradually, and the more you send the slower each call gets.

And, in Acumatica's own words: *"Acumatica ERP gives no indication that a request is added to the queue or being processed; the application that makes a request should stay connected and wait for the response."*

So the primary throttling signal is not an error. It is your requests getting slower. A call is only declined once the queue is more than 20 deep or it has waited 10 minutes — meaning a legitimately slow response can take minutes, and a client that times out aggressively will retry into the very queue that is already saturated. Treat slowness as backpressure, not failure.

Sessions leak in two ways

A session that is never logged out keeps its user slot. Log in, work, crash before logging out, and that slot is held until the server times it out on its own schedule. Do that a few times and no integration can sign in — including the customer's existing ones, which is how this becomes someone else's outage. The client always logs out on disconnect, and every widget render disconnects in a finally. Sign-out requests bypass the queue and are processed immediately, so logging out is always cheap.

A bearer token alone does not identify a session. If you authenticate with OAuth and send only the Authorization header, Acumatica treats each call as a new user and each one takes its own slot. The session cookie returned alongside the token is what says "same user, same session" — so cookies are captured from every response and replayed under both auth modes.

The customer can cap us specifically

An admin can limit sessions per integrated application on **User Types (EP202500) or per user on Users (SM201010)**. SM604000's Warnings tab flags any application opening more than three sessions at once. If a connection starts failing at sign-in on an instance that was working, this is the first place to look — someone may have capped the integration user deliberately, and that is a conversation, not a bug.

Practical consequences

• The client caps its own in-flight requests below the tier (four by default). Raise max_concurrent on the account only once you know the tier. On a trial instance the default is fine — a trial limits users, not concurrency, and we hold one session.
• Prefer one query returning fifty rows over fifty queries returning one. The per-minute budget makes chattiness expensive in a way concurrency alone does not.
• $expand is not free: each expanded collection is more work per row. Expand when fetching one document, not when scanning a page of them.
• A scene of eight tiles is eight renders. That is the realistic way to strain a tier by accident, which is why every tile shares the discipline above rather than opening its own long-lived session.
• Schema discovery is memoised per client, because probing versions costs up to nine requests and doing that once per parallel tool call would spend a large part of a minute's budget learning something that does not change.
• When a customer reports the ERP "crawling," ask them to open SM604000's Statistics tab. It shows delayed and declined request counts, which settles whether an integration is actually the cause — often it is not.