Rate limits and budgets

How the gateway meters you: rate_limited versus budget_exhausted, the rate-limit headers, spend caps, and reading your live headroom.

Two separate controls can refuse a request with 429: a rate limit on how fast you send requests, and a budget on how much you spend. The body's code tells you which one you hit, and they need different handling. Your account's limits are shown in your Console, and GET /api/v1/limits returns them, with live headroom, to your code.

rate_limited or budget_exhausted

Spend caps refuse with 429 too, under their own codes: a monthly cap on a key (key_spend_cap_exceeded), a monthly cap on a workspace (workspace_spend_cap_exceeded), and the credit pool (credits_exhausted). Like budget_exhausted, they mean an allowance is spent, and they clear only at reset_at or when the cap changes. Every 429 carries Retry-After; on these codes and on budget_exhausted it counts down to reset_at, and retrying sooner fails the same way.

POST /api/v1/moderations never returns budget_exhausted: moderation is exempt from the subscription pool, so a spent allowance cannot switch it off. It can still return rate_limited or a spend-cap code.

Rate-limit headers

Metered responses carry the state of the bucket the route is metered on:

The X-RateLimit-* headers always describe the per-minute request window, so a budget refusal can still show requests remaining.

The X-RateLimit-* headers are absent on a 401, because authentication runs before the limiter, and on a 403 from the key check (key_scope_forbidden, key_read_only). They are also absent when the limiter cannot reach its own storage; that request is served unmetered rather than refused.

# -D - prints the response headers; look for X-RateLimit-* and, on a 429, Retry-After.
curl -s -D - -o /dev/null https://api.cruxy.ai/api/v1/limits \
  -H "Authorization: Bearer $CRUXY_API_KEY"

// These clear only at reset_at; every other 429 clears after Retry-After.
const ALLOWANCE_SPENT = new Set([
  'budget_exhausted',
  'key_spend_cap_exceeded',
  'workspace_spend_cap_exceeded',
  'credits_exhausted',
])
 
const res = await fetch('https://api.cruxy.ai/api/v1/chat', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CRUXY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'mira',
    stream: false,
    messages: [{ role: 'user', content: 'Hello' }],
  }),
})
 
const remaining = res.headers.get('X-RateLimit-Remaining')
const resetAt = res.headers.get('X-RateLimit-Reset') // Unix seconds
 
if (res.status === 429) {
  const { code, reset_at, request_id } = await res.json()
  const waitSeconds = Number(res.headers.get('Retry-After'))
  if (ALLOWANCE_SPENT.has(code)) {
    // No retry succeeds before reset_at.
    console.log(`allowance spent: ${code}, resets at ${reset_at} (request_id ${request_id})`)
  } else {
    // rate_limited, or a transient headless check: wait Retry-After, then retry.
    console.log(`${code}; retry in ${waitSeconds}s (request_id ${request_id})`)
  }
} else if (remaining !== null) {
  console.log(`${remaining} requests left until ${new Date(Number(resetAt) * 1000).toISOString()}`)
}

Pace yourself before you reach 0: when X-RateLimit-Remaining runs low, slow down until X-RateLimit-Reset rather than waiting for a 429.

Read your limits

GET /api/v1/limits returns the limits that apply to your key, with live headroom. Every value comes from the same limiter and budget state that chat enforces, so remaining is exactly what your next request is checked against. The call costs nothing, writes nothing, and is rate-limited like any other route.

curl https://api.cruxy.ai/api/v1/limits \
  -H "Authorization: Bearer $CRUXY_API_KEY"

const res = await fetch('https://api.cruxy.ai/api/v1/limits', {
  headers: { Authorization: `Bearer ${process.env.CRUXY_API_KEY}` },
})
if (!res.ok) throw new Error(`limits request failed: ${res.status}`)
 
const limits = await res.json()
const perKey = limits.rate_limits.chat.per_key
console.log(`chat: ${perKey.remaining} of ${perKey.limit} left this window`)
 
if (limits.token_pool) {
  console.log(`token pool: ${limits.token_pool.state}`) // healthy, low, or blocked
}

Everything comes from the key you send; nothing is read from the request. Which blocks appear depends on your billing bucket:

token_pool has two windows, each with cap, used, remaining, resets_at, and a state of healthy, low, or blocked:

• monthly: the calendar-month cap.
• burst: the trailing 12-hour sliding cap.

It also carries an overall state, blocked_models, the unit (weighted_tokens), and mira, a monthly request cap on the mira tier with its own cap, used, remaining, resets_at, and state.

There is no tokens-per-minute limit and no per-model daily cap. The gateway enforces neither, so neither appears here.

Budgets and auto

A request with model: "auto" may be budget-downgraded to mira. Read cruxy.routed_tier on the response to see the tier that served it, rather than assuming the router's first choice; see Auto routing.

Next steps

• Errors and retries: every 429 code, and a retry loop that honours Retry-After.
• Features overview: the tiers and auto.
• Get your API key: key restrictions, including spend caps.