# Rate limits & budgets Per-key budgets, RPM ceilings, and how to handle 402 and 429. 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](https://docs.privatemind.com/messages-api.html) 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](https://docs.privatemind.com/errors.html#messages-api). ## 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: ```text HTTP/1.1 402 Payment Required ``` ```json { "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`](https://docs.privatemind.com/models.html#pricing) 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: ```text HTTP/1.1 429 Too Many Requests ``` ```json { "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 ```python 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](https://docs.privatemind.com/errors.html) for the full envelope around `402` and `429`. - [Authentication](https://docs.privatemind.com/authentication.html) for key shape and rotation. - [Usage](https://docs.privatemind.com/usage.html) for the API endpoint that surfaces spend programmatically.