Skip to main content
These limits protect the ingest infrastructure. They are not part of the Risk Score and they never change how a visitor is scored. The Risk Score is 0-100 (Clean / Low / Medium / High) and is driven entirely by the signals collected from a visitor. This page is about keeping the gateway healthy under load.
In normal use you rarely hit these limits. The snippet manages its own call cadence (one identify per visit, throttled by a session window), so a single visitor on a single page does not generate a burst of requests. Limits exist to absorb abusive traffic, not legitimate integration patterns.

​
The limits at a glance

The snippet posts collected signals to rest.shieldlabs.ai. That ingest gateway enforces three protections: All three are pure infrastructure guards on the ingest gateway. None of them feed the score, and none of them appear in the webhook or History API payloads as a signal. The Management API on api.shieldlabs.ai applies the same per-IP rate limit (20 req/min, 1-hour ban) and concurrency cap (512 in-flight) independently. A 429 or 503 there returns {"error":"too many requests"} or {"error":"server is busy"}. The History API on account.shieldlabs.ai is not subject to these gateway limits.

​
Per-IP rate limit and the 1-hour ban

A single source IP may make up to 20 requests per minute to the REST ingest endpoint. Cross that and the gateway returns:
After the threshold is crossed, that IP is banned for 1 hour. During the ban window, further requests from the same IP continue to be rejected with 429. The ban clears automatically; there is no manual unban step and nothing to configure.
Because the limit is per source IP, be careful in environments where many real users share one egress IP (a corporate NAT, a mobile carrier gateway, a shipping/CI proxy). In those setups a normal crowd of users can look like one busy IP. If you proxy snippet traffic through your own backend, you collapse every user onto your server’s IP and will hit this limit fast. Let the snippet post directly from the browser instead.

​
Guard against the “999” ban marker

When an IP is banned, the browser receives the 429, but your backend can still see a snapshot for that request: ShieldLabs writes a sentinel value of 999 to mark the banned request, and that snapshot can reach you on a webhook delivery or a History API row. The 999 is not capped to 100 on the ban path, so it arrives as-is. You may therefore receive a payload where data.risk_score (webhook) or Score (History API) is 999.
Guard for 999 before you read the band. A rate-limit ban is a gateway event, not a high-risk visitor, but its 999 marker can land in a webhook or History row uncapped. Drop those rows at the top of your handler:
Branch your decision logic only on a score in the 0-100 range. Read a 999 as “this IP was rate-limited at the gateway,” and look at the 429 status, not the number.

​
Concurrency cap (503)

Independent of the per-IP limit, the gateway caps the number of simultaneous in-flight requests across all traffic. When that cap (512 connections) is saturated, new requests get:
A 503 here means “try again shortly,” not “you did something wrong.” It is transient back-pressure. The snippet does not need special handling for this; if you call the Server API server-side and hit a 503, retry with a short backoff.

​
Request body size (512 KB)

Each request body to the REST gateway is capped at 512 KB. The signal payload the snippet sends is well under this in normal operation, so you will not approach the cap unless something is wrong upstream (for example, a payload being duplicated or wrapped before it reaches the gateway). Oversized bodies are rejected before scoring.

​
Billing exhaustion is separate (402)

Running out of request balance is not a rate limit. It is a billing condition with its own status code:
A 402 means the domain has no remaining request balance, so the call cannot be processed. This is unrelated to how fast you are sending traffic. Top up or upgrade the plan to clear it. The Billing page covers how requests are counted (one identify = one request), and the Errors page lists the full status-code reference.

​
How to stay within the limits

1

Let the snippet post from the browser

The snippet is designed to call rest.shieldlabs.ai directly from each visitor’s browser, so requests are naturally spread across many client IPs. Do not relay snippet traffic through a single server, which would funnel everyone onto one IP and trip the 20/minute limit.
2

Rely on the built-in session throttle

The snippet runs one identify per visit within a session window rather than on every interaction. You generally do not need to add your own debouncing. Use forceCheckAnonymous / forceCheckAuthenticatedUser only at meaningful moments (right after login, before a sensitive action), not in a loop.
3

Read results, do not poll the gateway

Get scores from the webhook (delivered automatically) or, when you need a guaranteed read, from the History API. Do not re-fire identify calls to “refresh” a score.
4

Back off on 503

For any server-side call, treat 503 as transient and retry after a short, jittered delay. Treat 429 as a hard stop for that IP until the ban window passes.

​
Quick reference

The Errors page documents every status code ShieldLabs can return and how to handle it.