Errors and limits
What each status code means, your requests- and tokens-per-minute allowance, and how prepaid credit is spent.
Errors
Errors follow the endpoint's dialect. /v1/messages and its token-counting route
use Anthropic's native envelope; the OpenAI-format endpoints — including
transcription — use { "error": { "message", "type", "param", "code" } }, so
their SDKs parse failures rather than reporting an opaque "unexpected response".
| Status | What happened | What to do |
|---|---|---|
401 | The key is missing, malformed, unknown, revoked or expired | Check the key. The response deliberately does not say which of those it was |
403 | Valid key, but the model is outside its allowlist | Widen the allowlist, or use a model the key may reach |
404 | Faucet does not carry that model | Check the slug against GET /v1/models |
400 | Real model on the wrong endpoint, or an unsupported parameter/format | The message names the endpoint or supported alternative; the slug is fine |
409 | A replayed Idempotency-Key on key creation | Nothing — the original key exists and no second one was minted |
413 | A transcription upload above the 25 MiB ceiling | Split the audio. The refusal happens before the body is read |
429 | Past the key's requests- or tokens-per-minute allowance | Back off — retry-after tells you how long |
402 | Out of prepaid credit, or past a monthly budget | error.param says which of the three: organization_balance — top up, and GET /v1/credits says how far under you are; organization_budget; or key_budget, this key's own monthly cap. code stays insufficient_quota for all three |
503 | Faucet carries the model but holds no credential that can serve it | Not your fault; try another model or wait |
A `401` from Faucet always means *your Faucet key* is bad
An upstream provider's 401 is never forwarded — it becomes a 502, so you
are never sent rotating a credential you do not own.
Your allowance
60 requests and 200,000 tokens per minute unless we have agreed otherwise
with you. The two are checked separately, so a 429 can come from either — the
message says which. Each key gets that allowance to itself rather than drawing on
a shared pool, and the figure comes from a default set on your organization: a
key can be held below it, so a batch job cannot starve everything else, but
never above it. If your workload needs more, ask rather than finding the ceiling
through a wall of 429s; telling us the rate you want to run at is enough.
Rate limits are leaky buckets that refill continuously rather than resetting on a minute boundary, so you cannot spend a whole allowance at 59.9s and another at 60.1s. Requests-per-minute is charged when the request is admitted; tokens-per-minute cannot be, because the count does not exist until the response does, so an overshoot is repaid out of the next window instead of forgiven.
Every endpoint debits the token bucket, image generation included — its output tokens are the image, and they are counted like any others. That is worth planning for, because they are large: one high-quality 1024×1024 image is a few thousand output tokens, so a modest tokens-per-minute allowance can be spent in a handful of pictures. The overshoot rule above is what you will feel first — the image that empties the bucket is served, and the next request waits.
Credit
Credit is prepaid and spent live. Between hourly settlements the balance you are admitted against includes unsettled spend, so a burst cannot overrun the balance and be discovered an hour later.
Ask for that live figure instead of waiting for the 402. Your key can read
its own credit, so a job that runs while nobody is awake can check before it
starts rather than failing halfway:
curl https://api.intfaucet.com/v1/credits \
-H "Authorization: Bearer $FAUCET_API_KEY"{
"object": "credits",
"available": "41103811", // balance − unsettled: what your next request is judged against
"balance": "41266136", // settled; what an invoice is rebuilt from
"unsettled": "162325", // billed, not yet drawn down
"currency": "usd",
"scale": 1000000
}available is the one to act on, and it is the only figure that matches what the
gateway will actually do — the console's settled balance can be a couple of hours
ahead of it. Divide by scale for dollars. The amounts are strings because
they are exact micro-dollar integers and a JSON number would quietly round them,
and available may be negative: that means a burst outran settlement, and it
is precisely the state behind a 402.
Turn on the low-credit warning under Notifications. Set a threshold and the organization's owners are emailed once when the live balance crosses it — including on the request that is about to be refused, because that is the moment someone most needs to know.
What a key can say about itself
This is the question to use when the figure you want is this key's allowance rather than the organization's credit:
curl https://api.intfaucet.com/v1/key \
-H "Authorization: Bearer $FAUCET_API_KEY"{
"object": "key",
"name": "production-web",
"prefix": "fct_live_",
"last4": "9f2c",
"monthly_budget": "20000000", // null when only the org cap applies
"month_spend": "7431902", // live, not settled
"month_resets_at": "2026-10-01T00:00:00Z",
"model_allowlist": ["anthropic/claude-sonnet-5"],
"rpm_limit": 60,
"tpm_limit": 200000,
"currency": "usd",
"scale": 1000000
}It describes the key you presented and no other. The two numbers a key_budget
402 is about are both here — month_spend against monthly_budget — and
month_resets_at is when the first returns to zero, sent as an instant so you do
not have to work out the month boundary yourself. rpm_limit and tpm_limit are
the limits actually enforced, after your organization's defaults have been
applied.
DELETE /v1/key revokes that same key. It is what a "sign out of this device"
button should call: forgetting a key locally leaves it spendable by whoever finds
it. Revoking twice is not an error — a changed field says whether that call was
the one that did it.