API Rate Limits Reference

AlloyScan applies two complementary controls to API consumers:

A monthly transaction quota (API transactions per month), tracked per site and reset on the site's Recharge day.
Server-side workload limits (per-second / per-minute ceilings on API transactions) introduced in release 25.14, enforced regardless of the monthly quota.

Limits

Limit	Where it lives	Behaviour
API transactions per month	`Admin Center > Site Settings > Limits and usage` (site-scope) and `Admin Center > App management > Billing > Limits and usage` (instance-scope)	Soft cap. Counter increments on every request and resets on the site's Recharge day. Sites may show `N used / Unlimited` if the cap is open.
API workload limits (per-second / per-minute)	Server-side, deployment-managed	Hard cap. Requests above the ceiling are rejected with HTTP 429. Exact ceiling values are not surfaced in the UI.

Note: The exact per-second and per-minute ceilings are not published in the product UI and may differ per deployment. Confirm with your administrator or your service contract if you need a precise figure.

Quota counter

The per-site API transactions per month value is visible to the site administrator at Admin Center > Site Settings > Limits and usage. The page shows <used> of <max> (or <used> of unlimited ∞ when the site cap is open) and the next Recharge day. Usage history is preserved on the same page.

A site value of Max # = 0 for API transactions means "no per-site cap — inherit the instance ceiling".

429 Too Many Requests

When the workload limit fires, the API returns:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "API workload limit exceeded"
}

Note: The exact response body and the presence of a Retry-After header are deployment-specific. Confirm against your instance's OpenAPI document. If Retry-After is present, honour it; if it is absent, use exponential backoff starting from 1 second.

Best practice

Cache the bearer token. Each token request counts against your monthly quota. Reuse a single token until it is within ~60 seconds of expiry, then request a new one. See API Authentication.
Batch where possible. Fetch lists with limit / offset rather than fetching one record at a time.
Back off on 429. Retry the failed request after the delay, and apply exponential backoff if a second 429 follows.
Monitor the monthly counter. Subscribe to the Administrative notification category so the site administrator is alerted before the monthly cap is hit.
Avoid polling tight loops. If you are watching for inventory changes, prefer a periodic full or filtered list (every 5 to 15 minutes) over per-second polling.

Quota exhaustion

If the monthly quota is reached on a site with a hard cap, further API calls are rejected until the next Recharge day, until the site cap is raised by a Global Administrator, or until the cap is removed by setting Max # = 0 (inherit instance limit).