When you reach the limit
What the API does when a workspace uses all of its monthly evaluation requests, and how SDKs, browsers, and OFREP providers behave.
When a workspace uses all of the evaluation requests that its plan allows, Toggld throttles it. Throttled means that the API refuses evaluation requests with HTTP 429 until the count window ends. Everything else keeps working.
When throttling starts
| Workspace | Throttled when |
|---|---|
| Free | It reaches 1M evaluation requests in the calendar month (UTC). |
| Pro without a spend cap | Never. Toggld bills the overage instead. |
| Pro with a spend cap | It reaches the request limit of the cap. See Spend cap. |
A Pro workspace with a failed payment keeps the Pro limits for 30 days. After that, it gets the Free limits. See Payment failure.
Toggld checks usage once an hour. Throttling can start up to about one hour after the workspace reaches its limit.
What changes
Throttling applies only to evaluation: OFREP evaluation requests and the evaluation stream.
| Traffic | While throttled |
|---|---|
POST /ofrep/v1/evaluate/flags/{key} and POST /ofrep/v1/evaluate/flags | HTTP 429 with a Retry-After header |
GET /eval/v1/stream (browser evaluation stream) | A new stream is refused with HTTP 429 and a Retry-After header. A stream that is already open closes with code 4402 (evaluation limit reached) within a few minutes. A context message sent on it while throttled closes it at once, and is not billed. |
Definition sync (/sync/v1/flags and /sync/v1/stream) | Keeps working |
Telemetry (POST /v1/telemetry) | Keeps working |
| Management API and dashboard | Keep working |
The Retry-After header points to the end of the count window. Refused requests are not billed.
Throttling never deletes or changes your flags.
How clients behave
JavaScript server SDK in sync mode (the default)
Nothing changes. In sync mode, the SDK evaluates in your process from its flag snapshot and sends no evaluation requests. Definition sync is not throttled, so the SDK keeps receiving flag changes.
If a sync request fails for any reason, the SDK keeps its last snapshot and evaluates from it.
Serverless client
Nothing changes, as in sync mode. The serverless client evaluates from its snapshot in memory, and snapshot refreshes are definition sync, which is not throttled.
JavaScript server SDK in remote mode
Remote mode (mode: "remote") sends one evaluation request per call, so throttling affects it:
- Typed getters and
evaluatereturn your fallback value. The details reportreason: "ERROR". evaluateAllreturns an empty array.- Evaluation never throws.
The SDK does not wait for Retry-After. Each call sends a new request and gets HTTP 429 until the window ends. To keep working while throttled, use sync mode, the default, on long-lived servers.
Browser SDK
- An open evaluation stream closes with code 4402. The SDK then evaluates over HTTP, which gets HTTP 429 with
Retry-After. Your nextsetContextorrefresh()call after that time tries the stream again. - A new stream is refused. A browser reports this only as a failed connection, so the SDK uses HTTP.
- HTTP evaluation requests get HTTP 429. The SDK keeps the values that it already has, and waits for
Retry-Afterbefore it tries again. For a flag without a value, it returns your default value. setContext(),refresh()andready()do not wait until the window ends. They resolve at once with the statuserror, and the SDK serves the values that it has or your defaults.- After the window ends, the SDK uses the stream again, also on later page loads.
Browsers and OpenFeature OFREP providers
A browser or an OFREP provider that evaluates remotely gets HTTP 429 for each evaluation request.
- With the
fetchexample on the Browser page, your code returns its fallback value for any response that is not successful. - To keep showing the last values that the user received, store the last successful bulk response, for example in memory or in local storage, and read from it when a request fails.
- Toggld does not maintain the OpenFeature providers. How a provider handles HTTP 429 and
Retry-Afterdepends on the provider and its version. Check its documentation.
In every case, always pass a safe default value when you read a flag. Your code receives it whenever an evaluation request fails, including when the workspace is throttled.
When throttling ends
Throttling ends when one of these happens:
- A new count window starts.
- The workspace upgrades to Pro. The throttle clears at once.
- An owner raises or removes the spend cap. The throttle clears at once.
After the throttle clears, the hosted API can take up to about one minute to accept evaluation requests at every edge location, because it caches credential data for up to 60 seconds.
Monthly limits and per-minute rate limits
Toggld has two kinds of limits. Both return HTTP 429 with Retry-After.
| Monthly evaluation limit | Per-minute rate limits | |
|---|---|---|
| Purpose | The plan's included usage | Protect the API from abuse and overload |
| Depends on the plan | Yes | No. The same on every plan. |
| Window | The count window: a calendar month or a billing period | 60 seconds |
| Applies to | OFREP evaluation requests and the evaluation stream | Every API request, in budgets by IP address, environment, and credential type |
Retry-After | The end of the count window | 60 seconds or less |
See Rate limits for the per-minute budgets.
Prepare for the limit
- Always pass a safe default value to every flag read.
- Use sync mode on long-lived servers. It is not billed, and throttling does not affect it.
- In browsers, call the bulk endpoint once per page load instead of one request per flag.
- Watch for the usage alerts at 80% and 100% of your limit.