Every PrivateMind API key has two separate controls: a budget cap (monthly spend) and a rate limit (calls per minute). We enforce both on the server, across the OpenAI-shaped API and the Messages API together: a key has one budget and one limit for both. On the Messages API the same conditions return billing_error (402) and rate_limit_error (429). See Errors.
Budgets
A key can have a monthly spending cap in USD. You set it when you create the key and can't change it later. Every key you own also draws on your own monthly budget, so a cap can only lower the limit. Every request's prompt_tokens + completion_tokens is priced and added to the key's spend for the current month. Spend resets on the first of each calendar month (UTC). When spent_usd >= budget_usd, calls return:
HTTP/1.1 402 Payment Required{
"error": {
"message": "Budget exceeded. Spent $10.00 of $10.00 budget. Ask your org admin if you need more.",
"type": "budget_exceeded",
"code": "budget_exceeded"
}
}A 402 can also carry org_budget_ceiling_exceeded when your organisation's own limit is reached, or credit_exhausted when a free credit is used up.
To recover, create a new key with a higher cap and revoke the old one, or wait for the monthly reset.
How spend is calculated
Each model has an input-token cost and an output-token cost. GET /v1/models returns each model's published rates in its cost object. Streaming and non-streaming responses are priced the same. On a stream, the final usage block has the authoritative counts.
Embeddings are priced on input tokens only (completion_tokens is always 0).
Spend is updated after each request completes, so you can't see it while a request is running. If you need finer tracking, instrument your client.
Rate limits
Each key has a requests-per-minute (RPM) limit, counted over a sliding window. Going over it returns:
HTTP/1.1 429 Too Many Requests{
"error": {
"message": "Rate limit exceeded",
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}The limit is per key, not per organisation or per IP address. If one workload needs more requests per minute than one key allows, create a second key with the same budget and alternate between the keys in your client (round-robin). Each key keeps its own budget cap, and spend from all of them adds up to your own monthly budget and your organisation's.
Backoff
import random, time, openai
def call_with_retry(fn, max_attempts=5):
for attempt in range(max_attempts):
try:
return fn()
except openai.RateLimitError:
if attempt == max_attempts - 1:
raise
delay = min(30, (2 ** attempt) + random.random())
time.sleep(delay)Designing around the limits
- One key per workload. Don't share a key across unrelated services, or one misbehaving service can burn through the others' budget.
- Tight budgets in dev. A runaway loop in a notebook can spend a month's quota in an hour. Use a separate dev key with a low cap.
- Watch token usage in responses. Every response includes
usage. Write it to your logs. - Cache where you can. Identical embedding queries can be cached client-side.
Where to view spend
The API Keys page in the app shows each key's spend and recent activity next to the key list. You create and revoke keys there too.
Where next
- Errors for the full envelope around
402and429. - Authentication for key shape and rotation.
- Usage for the API endpoint that surfaces spend programmatically.