Set usage controls

This guide will show how to combine rate limits, quotas, and budgets across projects, keys, and end users to keep usage and cost within bounds. Roadie enforces three kinds of control in the gateway, against Redis, before your provider key is ever charged. This guide is the task-oriented walkthrough; for the enforcement model (precedence, kill-switch semantics, headers), see Rate limits, quotas & budgets. All three are control-plane writes on , gated at projects.write. Each write publishes config-dirty so the gateway picks it up on the next snapshot load.

Pick a scope

Every rate limit and quota attaches at a scope. The gateway enforces the most specific policy per dimension and every applicable level, so a request can be checked against its end-user, key, environment, and project limits at once.

Scope	Applies to	Needs `scope_ref`?
`project`	Every request in the project	No
`environment`	Every request in the path environment	No (anchored to the path env)
`key`	One API key	Yes — the key id
`model`	One `provider/model` id	Yes — the model id
`end_user_default`	Every end user	No
`end_user_plan`	End users on one asserted/entitled plan	Yes — the plan name (e.g. `pro`)

scope_ref is required for key, model, and end_user_plan, and forbidden for the others — sending it (or omitting it) incorrectly is a 400.

1. Add a rate limit

Rate limits cap requests per second/minute/day and max concurrency. A burst_multiplier allows short bursts while bounding the sustained rate. At least one of rps, rpm, rpd, or max_concurrency must be set. This example caps every end user on the free plan to 20 requests/minute and 2 concurrent requests:

curl -X PUT https://api.roadie.paroaria.ai/v1/environments/$ENV_ID/rate-limits \
  -H "Authorization: Bearer $ROADIE_MGMT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "end_user_plan",
    "scope_ref": "free",
    "rpm": 20,
    "max_concurrency": 2,
    "burst_multiplier": 1.5
  }'

List what is configured for an environment with GET /v1/environments/{envId}/rate-limits.

2. Add a quota

A quota caps a metric over a fixed calendar window (day or month). The metric is one of requests, input_tokens, output_tokens, total_tokens, or cost_usd. Set mode to hard to block, or soft to alert only; a grace_pct on a hard quota admits N% overage before blocking. This caps the project to 5,000,000 total tokens per day, hard, with 10% grace:

curl -X PUT https://api.roadie.paroaria.ai/v1/environments/$ENV_ID/quotas \
  -H "Authorization: Bearer $ROADIE_MGMT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "project",
    "window": "day",
    "metric": "total_tokens",
    "limit": 5000000,
    "mode": "hard",
    "grace_pct": 10
  }'

A quota is pre-checked with an estimate and then corrected with actuals by the metering pipeline. Windows are keyed by UTC date and self-expire — there is no reset job. List with GET /v1/environments/{envId}/quotas.

3. Set a spend budget

A budget is a USD spend cap for the project, enforced with a reserve/settle scheme so concurrent requests cannot collectively overrun it. It is a project-level write:

curl -X PUT https://api.roadie.paroaria.ai/v1/projects/$PROJECT_ID/budget \
  -H "Authorization: Bearer $ROADIE_MGMT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "period": "monthly",
    "amount_usd": 500,
    "action_on_exceed": "block",
    "hard_cap": true,
    "notify_thresholds": [0.8, 1.0]
  }'

period — monthly or daily; the accounting window is UTC-aligned.
action_on_exceed — block enforces the cap (a request over the cap fails 402 budget_error); notify alerts without blocking.
notify_thresholds — fractions of the budget at which the account owner is emailed (e.g. 0.8 = 80%, 1.0 = 100%).

Check current spend against the cap with GET /v1/projects/{projectId}/budget/status.

Soft vs hard: what “exceeded” does

Every threshold is either soft or hard:

Soft never blocks. Crossing it sends an email alert to the account owner (once per window per threshold) — an early warning.
Hard rejects the request: 429 rate_limit_error / quota_error, or 402 budget_error, with Retry-After where meaningful.

Alerts are delivered by email to the account owner. Roadie does not send outbound webhooks for limit or budget events.

Handle the errors in your app

The SDK surfaces rate-limit state on every response and raises typed errors when a hard limit trips:

import { RateLimitError, QuotaError, BudgetError } from '@roadie/sdk';

try {
  await roadie.chat.create({ model: 'openai/gpt-4o', messages });
} catch (err) {
  if (err instanceof RateLimitError) {
    // transient — the SDK already retried; wait err.retryAfter and try later
  } else if (err instanceof QuotaError) {
    // a usage window is exhausted — surface a "limit reached" state
  } else if (err instanceof BudgetError) {
    // spend cap hit (402) — the account owner has been alerted
  }
}

On the OpenAI-compatible surface, both quota and budget rejections are reported as insufficient_quota at 429, because the OpenAI error schema has no 402.

Limits, quotas & budgets

Precedence, headers, and reconciliation.

Per-user limits tutorial

Cap an individual end user step by step.

End users & entitlements

Per-plan presets and blocking abusers.

Observability: logs & usage

Watch usage and spend against your limits.

Get started

Core concepts

Guides

SDKs

Set usage controls

Pick a scope

1. Add a rate limit

2. Add a quota

3. Set a spend budget

Soft vs hard: what “exceeded” does

Handle the errors in your app

Limits, quotas & budgets

Per-user limits tutorial

End users & entitlements

Observability: logs & usage

​Pick a scope

​1. Add a rate limit

​2. Add a quota

​3. Set a spend budget

​Soft vs hard: what “exceeded” does

​Handle the errors in your app

​Related

Limits, quotas & budgets

Per-user limits tutorial

End users & entitlements

Observability: logs & usage

Pick a scope

1. Add a rate limit

2. Add a quota

3. Set a spend budget

Soft vs hard: what “exceeded” does

Handle the errors in your app

Related