Build
Limits.
What a key may do, what it has left, and what a refused request looks like. There is no platform cap on what you spend, and requests with an API key have no request-rate cap. A limit exists only where you set one: on a key, or on your Foundry wallet.
The live figures are two reads: GET /v1/limits, every limit the gateway enforces, and GET /v1/key, the calling key's budgets and what is left of them.
The two reads
curl https://api.usdf.fi/v1/limits -H "Authorization: Bearer $USDF_API_KEY" curl https://api.usdf.fi/v1/key -H "Authorization: Bearer $USDF_API_KEY"
GET /v1/key describes the key it is sent with:
| Field | What it is |
|---|---|
limit, limit_, limit_ | The figures of the key's budget that binds first, in USD (1 USDF = $1). limit_ is daily, weekly or monthly, or null for a lifetime budget. All three are null for a key with no budget. |
budgets | Every budget on the key, each with its limit_, spend_, remaining_, reset_ and resets_. remaining_ never goes below 0. |
usage, usage_, usage_, usage_ | What the key spent in all, and in the current UTC day, week (from Monday) and month. |
rate_ | The key's own request-rate limit where its owner set one: requests and interval: "1m". requests is -1 for none. |
usdf | Each amount exactly, in USDF base units (1 unit = 0.000001 USDF). |
- Requests from a funded balance have no request-rate cap. A key is held to one only where its owner sets one:
rate_limit_rpm, 1 to 5,999 requests a minute, onPOSTorPATCH /v1/account/keys; a team key and a platform's sub-key take it too, andnullremoves it. A key made without one has none. - Requests paid one at a time with x402 (no key) have no per-payer cap either. One payment per payer settles at a time, beside the per-address and settlement limits that protect the payment flow. The live figures are
x402inGET /v1/limits. - Protection against abuse: limits per address on sign-in and key management, per key on the key and credit reads, per address on every public read, and flood protection at the edge. A client using its key at an ordinary pace never meets them.
A key has no spend limit until its owner sets one. A new key starts with none, and nothing on the platform caps what a funded account spends. A key can carry spend limits of three kinds. Each is set by the key's owner and checked before a request is sent on:
- A lifetime budget (
budget_unitsonPOSTorPATCH /v1/account/keys): the most the key may ever spend. - Budgets that start again at 00:00 UTC: per UTC day, per week (from Monday) and per calendar month, set with
PATCH /v1/keys/{id}andbudget_day_units,budget_week_unitsorbudget_month_units, in USDF base units;nullclears one. What the key spent since the period began, what its requests in flight hold and the new request's own hold must fit together, so requests that start at once cannot pass a budget between them. - Trailing caps: per trailing hour, 24 hours and 30 days (
spend_limit_hour_units,spend_limit_day_units,spend_limit_month_units). They roll continuously rather than at midnight.
A request that does not fit is refused before anything runs, and nothing is charged; a smaller request, with a lower max_tokens, may still fit. The refusal is 402, with the limit named in error.metadata:
402 key_budget_exceeded
{
"error": {
"message": "this request may cost up to 0.020000 USDF, and this key's budget of 1.000000 USDF for the UTC day has 0.010000 USDF left ...",
"type": "insufficient_quota",
"param": null,
"code": "key_budget_exceeded",
"metadata": { "limit_source": "key_limit", "reset_interval": "daily", "resets_at": "2026-11-07T00:00:00.000Z" }
}
}limit_source is key_limit for a key's budgets (reset_interval is null for the lifetime one) and key_spend_limit for its trailing caps, which answer spend_limit_exceeded with window 1h, 24h or 30d. Raising or clearing a budget or a cap may ask for a recent sign-in (403 reauth_required); lowering one never does. GET /v1/keys/{id}/limits shows each of them with what was spent.
A balance that is spent answers 402 insufficient_balance. Fund the account, and the key serves again on its next request. See Accounts and keys.
When you pay from your own Foundry wallet, the wallet has no daily limit of its own until you set one, in Settings (Foundry wallet) or with POST /v1/account/foundry-wallet/limit.
Every 429, whichever limit answered it, has the same body and headers:
429 rate_limited
{
"error": {
"message": "rate limit of 120 requests/minute exceeded",
"type": "rate_limit_error",
"param": null,
"code": "rate_limited",
"metadata": { "error_type": "rate_limit_exceeded" }
}
}| Header | What it says |
|---|---|
Retry-After | Seconds to wait. |
X-RateLimit-Limit | The limit that answered, in requests per its window; 0 where it is not a count of requests, such as an address held off for a while. |
X-RateLimit-Remaining | 0 |
X-RateLimit-Reset | When a request is let through again, in milliseconds since the epoch. |
code says which limit it was: rate_limited, payments_busy, payment_in_flight, key_misses and the others GET /v1/limits lists. Browsers can read all four headers. Every limit is checked before a request is sent on, so a stream that has started is never cut by one.
GET /v1/limits takes an API key or a session. What it holds:
| Field | What it holds |
|---|---|
keys | The requests-per-minute limit a key's owner may set on it (rate_, 1 to 5,999). None by default. |
public_ | One limit per caller IP address, shared by every GET with no key. |
x402 | Requests paid per request: per_, per_, shared and in_. |
mcp, tools | Notes, not limits of their own: both share keys for calls with a key, and public_ for public listings. |
agents | writes (creating, funding or changing an agent) and reads. |
connect | platform_, sub_ and public_. |
account | Session and account limits: the dashboard's reads, key management, top-ups and the like. |
wallet | Sign-in links, sign-in nonces and the wallet reads with no key. |
other | The pay-with-any-token quote, the pool read, a send link's public read, and video and batch job reads. |
early_ | Not a refusal: the requests a key may leave before their first output at no charge, per UTC day. |
settlement | How long settling a payment paid per request takes, at p50 and p90. |
The docs home lists the main figures in Rate limits.