Skip to main content
MeshAPI enforces four kinds of ceiling on every request: Exceeding a rate limit returns 429. Exceeding a spend cap or running out of credit returns 402.

​
Defaults

A key with nothing configured still has limits:
The spend cap is the one default that is not protective. An unset spend cap means unlimited spend against your balance, not zero. If you want a key to be unable to burn your whole balance, you must set spend_cap_usd explicitly.
A key with no tpm_limit is not throttled on tokens. GET /v1/usage/rate-limits still shows a TPM limit for it: a display value with is_default_limit: true, not an enforced one. How high you can set a key yourself depends on your organization’s rate-limit tier: Requests to set a key above your tier’s ceiling are rejected with 422. Limits above your tier are granted by MeshAPI support, up to a platform ceiling of 100,000 RPM and 10,000,000 RPD.

​
Where limits can be set

Limits exist at five scopes:
  1. Key — rpm_limit, rpd_limit, tpm_limit, spend_cap_usd
  2. Team member — that person’s ceiling within one team
  3. Org member — that person’s ceiling across the org
  4. Team
  5. Organization
All of them default to unlimited except the key-level defaults above. A key-scope spend cap counts every request the key has ever made. The scopes above it count only the last 30 days, so spend there ages out on a rolling basis and there is no monthly reset date.

​
Which person a member limit applies to

A member limit is attributed to whoever created the key, not whoever sends the request. An inference request carries a key and nothing else, so the API cannot tell two people apart. The key is the identity. If several people share one key, all of their usage counts against the creator’s member limit, and the other people’s own limits do nothing at all. When that one limit runs out, the key returns 402 for everyone holding it.
Issue one key per person if you want per-person limits to mean anything. Member limits cannot restrict a shared key per human — they only ever restrict the person who created it.
A key also keeps counting against its creator’s limit after that person leaves your organization, until someone revokes the key.

​
Minimum wins

When more than one scope applies, the smallest value wins — limits restrict, they never raise. A key with 500 RPM inside a team capped at 100 RPM is effectively limited to 100. This means raising a key’s limit has no effect if a tier above it is lower. To actually widen a limit you must raise every tier that binds.

​
Checking the resolved value

Rather than working it out by hand, ask the API:
The response returns both the raw key-level values and the effective_* values after the minimum-wins resolution, along with the org, team, and member context that produced them — so you can see which tier is binding.
This endpoint takes an admin key (mak_...), not an rsk_ key. Key management and inference are separate credentials. Create one in Dashboard → Settings → Admin keys; see API Keys. The same resolved limits are shown on the key’s page in the dashboard.

​
Request body size

Every endpoint has a hard ceiling of 32 MiB (33,554,432 bytes) on the total request body, independent of your key, team, or org configuration. It is not raisable. An oversized request is rejected at the edge, before it reaches MeshAPI. That has consequences worth knowing, because it does not look like the other errors on this page:
  • the response is a plain HTML 413 Request Entity Too Large page, not a Mesh JSON error envelope — SDKs and error parsers will fail to decode it
  • there is no request_id, and the request does not appear in your usage or error logs
  • it is not billed, and it does not consume RPM/RPD
The usual cause is Base64-inlined media — images in /v1/chat/completions or /v1/responses, reference images in /v1/images/generations, audio or video inputs. Base64 inflates a payload by roughly 33%, so a single ~24 MB file already exceeds the limit once encoded. To stay under it:
  • send a public URL instead of Base64 wherever the endpoint accepts one
  • for large files, upload via the Files API and reference the returned file ID
  • downscale or re-compress images before encoding — vision models gain nothing from a 20 MB source image

​
Watching your usage against limits

GET /v1/usage/rate-limits reports current consumption against your limits — see the Usage & Monitoring API. Inference responses also carry your key’s request-rate state in OpenAI-style headers, so a client can slow down before it hits a 429: They report RPM only; there are no token headers. They also reflect the key alone: org, team, and member caps are not counted, so a 429 can arrive while remaining is above zero. A 429 carries a Retry-After that is the time to the window reset plus up to 5 seconds of random jitter, so clients rejected together do not all retry at the same instant.

​
Behaviours worth knowing

A spend cap can be exceeded by one request. Billing settles after a response is produced, because the true token count isn’t known until then. The final request that crosses the cap completes and is charged; the next one is rejected. For the same reason your balance can go slightly negative. Treat the cap as “stop shortly after this”, not a hard transactional ceiling. Free models still consume rate limits. A model priced at zero costs nothing against your balance or spend cap, but it consumes RPM and RPD like any other request. Free-model requests also have a tighter limit of their own: 20 RPM and 200 RPD per key, counted across all free models together. Memory injection is checked twice. Attaching a memory grows the prompt, so the spend cap is re-evaluated against the assembled request. A key near its cap can be rejected once memory is attached even though the raw request would have passed. See Memory. allowed_models interacts with limits in a surprising way. Restricting a key to a model list is an access control, not a limit — but it silently breaks features that route to models outside the list. See API Keys.