Key limits, from spend caps to path rules
Each Keylayer key can carry spend caps in dollars, request caps per UTC hour, day, week or month, a rate of 1 to 1,000,000 requests a minute, a limit of 1 to 10,000 requests at once, an expiry, and IP, method and path rules. Keylayer checks every one of them before it forwards a request, and each refusal carries a keylayer-error header that names the limit.
Every limit at a glance
| Limit | Dashboard field | Values | Window | Refused with |
|---|---|---|---|---|
| Spend cap | Spend in dollars | Dollars per period, hard or estimated | UTC hour, day, week, month | 403 budget_exceeded |
| Request cap | Requests | 1 to 1,000,000,000 per period | UTC hour, day, week, month | 429 quota_exceeded |
| Rate | Requests a minute | 1 to 1,000,000 | Rolling 60 seconds | 429 rate_limited |
| Concurrency | Requests at once | 1 to 10,000 | Requests in flight | 429 concurrency_limit |
| Expiry | Stops working (UTC) | A time within the key's lifetime | None | 401 expired |
| Lifetime | Lifetime | 1 hour by default, up to 365 days | None | 401 key_expired |
| Status | Status | Active or Suspended | None | 403 suspended |
| IP allowlist | Only from | Up to 64 IP addresses or CIDR ranges | None | 403 ip_not_allowed |
| Methods | Only methods | Up to 16 HTTP methods | None | 403 method_not_allowed |
| Paths | Only paths | Up to 64 path patterns | None | 403 path_not_allowed |
| Label on minted keys | Label, under Keys it mints | Optional or Required, on a minting key | None | 400 label_required, when minting |
| Lifetime of minted keys | Live at most, under Keys it mints | 1 minute to 365 days, on a minting key | None | Nothing; a longer lifetime is shortened |
The last two rows apply when a minting key mints, not to requests, and label_required carries no keylayer-error header.
Some limits are fixed:
- A request can run for 900 seconds on OpenAI, Anthropic, Google AI, Groq, Mistral, OpenRouter, Hugging Face and ElevenLabs, and 120 seconds on GitHub, Replicate and Resend. Past that, Keylayer ends it with 504 deadline_exceeded.
- On every built-in provider except Groq, routes that manage the provider account are blocked with 403 path_not_allowed. See admin routes and escape hatches.
- When the key or a key above it has a spend cap, the request body can be at most 16 MiB (413 body_too_large_for_budget).
- On the free plan, each credential relays at most 5,000 requests per UTC day and 60 a minute across all its keys. A request refused as 403 unpriced_operation counts toward both, like a relayed one. Past the 5,000, Keylayer answers 429 daily_cap until 00:00 UTC. Past the 60, it answers 429 rate_limited. As with a key's requests a minute, Keylayer counts the last 60 seconds in 10-second steps, and retry-after says when the oldest of them leaves the window. Pro has neither limit, and the flood limit below still applies. Pricing compares the plans.
- On a busy day for the free plan, the free workspaces using the most get 429 free_tier_limited until 00:00 UTC. None is limited before it has made 1,000 requests that day, refused ones included, and Pro workspaces never are.
- Each workspace's dashboard takes at most 60 actions a minute that need the owner's sign-in, such as listing, minting, editing or revoking keys, enrolling a credential or opening the vault, and 800 in any 24 hours. Revoking a key or credential and resetting the vault still work past 800, up to 1,000 in any 24 hours. Past any of these, Keylayer answers 429 rate_limited, and retry-after says when the next one is allowed.
- A credential takes at most 100 limit changes per UTC day from the dashboard, another 100 from all minting keys below the root, and 100 provider key rotations. Past that, Keylayer answers 429 mint_rate_limited until 00:00 UTC. Pausing a key still works past it, and doesn't count toward it.
- A credential holds at most 500 live keys on the free plan and 5,000 on Pro, and minting keys below the root stop 50 short of that. Past it, a mint gets 409 too_many_keys. When Pro ends, no key is revoked, but mints get 409 too_many_keys until the credential is back under the free plan's limit. See how deep keys go and how many.
- When Keylayer's activity storage is full, a free workspace using more than its fair share of it sees new activity, and keys made meanwhile, in the dashboard only once space frees up. Its keys keep relaying until one of its credentials has 1 GiB or 2,000,000 events waiting, which takes at least five days at the free plan's daily limits. From then until space frees up, Keylayer answers that credential's requests and mints with 503 trail_backlog, and retry-after says when it next tries to catch up. Keys below a minting key other than the root, and that minting key's own mints and limit changes, get it at half those limits, 512 MiB or 1,000,000 events, while keys minted straight from the root, such as the ones you mint in the dashboard, keep relaying up to the full ones. Revoking or pausing a key works past both. If Keylayer's database itself runs short of space, every free workspace's new activity waits the same way, and its vault activity too as space runs shorter. A paid workspace keeps its activity for 90 days or its newest 1,000,000 events, whichever is less. Its new activity waits only past 5,000,000 requests in a UTC day, until 00:00 UTC, or at the database's last limit, where its vault activity waits too, and either way its keys keep relaying until one of its credentials has 1 GiB or 2,000,000 events waiting. As space runs shorter, a free workspace's dashboard actions that need the owner's sign-in get 429 rate_limited too, except revoking a key or credential and resetting the vault. At the last limit every workspace's do, those included.
- The relay's flood limit applies on every plan. It allows 3,000 requests a minute per key, 600 per credential, 600 per IP address (per /64 for IPv6) and 6,000 per zone for requests from Cloudflare Workers, in each Cloudflare location. Past it, Keylayer answers 429 rate_limited with retry-after 60.
Only the flood limit and the free plan's busy-day limit count refused requests. Refusals from request caps, spend caps and the free plan's daily cap carry a retry-after header with the time until the period resets. Errors covers every code.
Spend caps
A spend cap limits what a key spends with the provider per UTC hour, day, week or month. You can set one cap per period, and every cap applies at once. One mode, hard or estimated, covers all of a key's caps.
Hard and estimated caps
Hard and estimated caps both work on OpenAI, Anthropic, Google AI, Groq and Mistral. OpenRouter, Hugging Face and ElevenLabs take estimated caps only. GitHub, Replicate and Resend take request caps but no spend caps. A mode the provider doesn't support is refused with 400 budget_mode_unsupported.
Spend caps covers what each mode reserves, charges and refuses.
Request caps and rate
Request caps count requests per UTC period: the clock hour, the day, the week from Monday 00:00 UTC, and the month from the 1st at 00:00 UTC. You can set one cap per period, and every cap applies at once.
Requests a minute is a rolling window. Keylayer counts the requests of the last 60 seconds in 10-second steps, and a refusal says when the oldest of them leaves the window.
Requests at once counts requests still running, streams included. A refusal asks you to retry after 1 second.
Expiry and status
Stops working (UTC) ends a key at a set time. Until then, you can change it, as long as it stays within the key's lifetime. The lifetime itself is fixed at mint. Status set to Suspended pauses the key until you set it back to Active. Both also stop every key below. See pausing a key.
IP allowlist
Only from takes up to 64 IPv4 or IPv6 addresses or CIDR ranges, such as 192.0.2.0/24 or 2001:db8::/32, matched against the address the request comes from.
Warning: Code on Cloudflare Workers reaches the relay from addresses it shares with every other Worker, so an allowlist can't tell your Worker apart. Use it for servers with fixed outbound addresses.
Methods and paths
Only methods takes up to 16 HTTP methods in capitals, such as GET and POST. Cloudflare refuses TRACE with 405 and CONNECT with 400 before they reach the relay, with no keylayer-error header, and a request with a method override header such as x-http-method-override, or a $httpMethod query parameter, gets 400 method_override.
Only paths takes up to 64 patterns, matched against the path you send to the relay without the query string. For Hugging Face's router, that path includes the /-/router prefix.
- A literal segment matches only itself, case included. A trailing slash makes a different path.
*matches exactly one whole segment and can't share a segment with other characters.**as the last segment matches the rest of the path, including nothing.- There are no regular expressions. A pattern starts with / and is at most 512 characters.
/v1/chat/completions matches /v1/chat/completions only
/v1/models/* matches /v1/models/gpt-5.4-mini, not /v1/models
/v1/** matches /v1 and everything below itAdmin routes and escape hatches
On every built-in provider except Groq, Keylayer blocks the routes that manage keys, organizations and account settings with 403 path_not_allowed, so an agent can't create provider keys or change your account. Examples are /v1/organization/** on OpenAI and /v1/organizations/** on Anthropic.
Escape hatches lift that block for one key. Under an estimated cap, they also let through unknown models, work billed after the response and writes Keylayer can't price, at the body-size estimate, so the cap can't see what those calls cost; a hard cap still refuses them. They never let through a POST to a route Keylayer prices spelled another way, such as with a trailing slash, other capitals or a .json ending, since the provider can bill it at that route's price. Only you can turn them on: click Escape hatches on the key's row and approve in your vault. Like Edit limits, it only appears on keys minted straight from your vault's root key. Child keys never inherit escape hatches.
Limits on child keys
A child key never has looser limits than its parent. Each number takes the smaller of the two, a hard parent cap keeps the child hard, and path patterns and IP ranges must sit inside the parent's. Every request is also checked against every key above it. See child keys and limit clamping.
How fast changes apply
A change applies to the next request. Keylayer never caches an approval, but each relay instance can remember a refusal for up to 5 seconds, so a loosened limit can take that long to apply. Running requests are checked again every 10 seconds, and only a pause, revoke or expiry stops one.
What the dashboard can't change after minting
Edit limits in the dashboard changes Status, Stops working (UTC), Requests a minute, Only paths, Requests and Spend in dollars, and on a minting key Keys it mints. Clearing a field there drops the key's own limit, so its parent's limit applies again, if it has one. The dashboard can't change Requests at once, Only from or Only methods after minting, and nothing changes a key's label, kind or lifetime. To change those, mint a new key and revoke the old one.
Updated