Short answer. Use the plan's daily request and token caps as the outer hard limit, a project dollar cap for each cost centre, and an application budget for each key. Read
X-Plugsky-Quota-Warningat 80%, treat 429 as a quota or rate response, and treat 402 as a project budget stop. Reconcile your ledger againstGET /v1/plugsky/usageevery day.
Hard versus soft caps
| Control | Scope | At the threshold | Who configures it |
|---|---|---|---|
| Plan daily caps | Workspace | 429 at 100%; reset 00:00 UTC | Plan |
| Project dollar cap | Project | Soft alerts at 50/80/95%; 402 at 100% | Dashboard |
| Warning header | Hobby / Starter | X-Plugsky-Quota-Warning at 80% | Automatic |
| Application budget | Key, tenant or feature | Your code rejects or downgrades | Your service |
| Spend alert | Billing or FinOps | Email or webhook; traffic continues | Dashboard / finance |
A soft cap is a promise to look; a hard cap is a promise to stop. Use both. The dangerous configuration is a soft cap with nobody watching it, because traffic continues and the alert becomes noise.
The 80% warning header
At 80% of a Hobby or Starter daily cap, the API adds X-Plugsky-Quota-Warning to the response. It is easy to miss because the request still succeeds. Log it on every response and attach it to the request ID and key ID.
import requests
resp = requests.post(
"https://api.plugsky.com/v1/chat/completions",
headers={"Authorization": f"Bearer {key}"},
json={"model": "plugsky-pro", "messages": messages},
timeout=60,
)
warning = resp.headers.get("X-Plugsky-Quota-Warning")
if warning:
metrics.increment("quota.warning", tags={"key_id": key_id})
log.warning("quota warning", extra={"key_id": key_id, "detail": warning})
Alert on the first warning, not the hundredth. Route it to the owner of the key and to the person who can raise the cap. If the warning is normal because the workload always runs near the cap, the plan is wrong, not the alert.
Per-key and per-project budgets
Plan caps are per workspace. Most teams need a smaller unit: a project, a customer or a feature. Use a separate API key per project, then keep a budget counter beside the key. The counter should be checked before the request, incremented after the response, and reconciled against the usage endpoint daily.
import time
def reserve(key_id, estimated_tokens, limit, redis):
day = time.strftime("%Y-%m-%d")
bucket = f"budget:{key_id}:{day}"
used = int(redis.get(bucket) or 0)
if used + estimated_tokens > limit:
raise BudgetExceeded(key_id)
pipe = redis.pipeline()
pipe.incrby(bucket, estimated_tokens)
pipe.expire(bucket, 172800)
pipe.execute()
def settle(key_id, estimated_tokens, actual_tokens, redis):
day = time.strftime("%Y-%m-%d")
delta = actual_tokens - estimated_tokens
if delta:
redis.incrby(f"budget:{key_id}:{day}", delta)
Estimate tokens before the call with a tokenizer, then settle with the usage block from the response. If the estimate is low, the counter drifts; reconciliation catches it. Store the budget in the same region as the application, not in a spreadsheet.
429 and 402 behavior
| Status | Meaning | Retry? | Action |
|---|---|---|---|
429 + Retry-After | Rate or concurrency limit | Yes, after the delay | Back off; shed low-priority work |
| 429 quota | Daily request or token cap | No until reset | Upgrade or wait for 00:00 UTC |
| 402 | Project budget cap reached | No | Raise the cap; alert finance |
| 401 / 403 | Bad key or missing scope | No | Fix credentials; do not rotate blindly |
| 503 | Upstream unavailable | Yes, once | Failover; check status page |
The 402 is the one teams forget. It is a budget decision, not a transient error, so a retry loop will burn time and hide the real problem. Surface it to the user with a clear message and a path to the budget owner.
Cost attribution and reconciliation
Attribution needs a key, a project and a user tag. Send the optional user field for the tenant or end user, use one key per environment, and log model, prompt tokens, completion tokens, latency and request ID. Then aggregate by the dimensions finance asks for.
| Dimension | Source | Use |
|---|---|---|
| Project | Key prefix or project ID | Chargeback, budget cap |
| Tenant / user | user field | Unit economics, abuse detection |
| Model | Response model | Cost and quality comparison |
| Tokens | usage block | Capacity planning |
| Feature | Your tag or route | Product-level margin |
Reconcile daily: sum the ledger by key and day, compare it with GET /v1/plugsky/usage, and investigate any variance above 2%. Late-arriving events, retries and streaming cancellations are the usual causes. At month end, compare the daily ledger with the invoice; a flat plan should match the plan fee, not a token total.
For the finance view, see AI cost governance for flat-rate plans and the LLM cost calculator. For current plan caps, see pricing; for the usage endpoint, see the docs.
FAQ
What is the difference between a hard and soft cap?
A soft cap alerts or throttles but still allows traffic. A hard cap stops requests when the tracked amount is reached. On Plugsky, plan token and request caps return 429 at 100%, and a project dollar cap returns 402 at 100%.
What does the 80% warning header mean?
At 80% of a Hobby or Starter daily cap, the API returns an X-Plugsky-Quota-Warning header. It is advisory; the request still succeeds. Log it and alert before the 100% response turns into a 429.
Can I set a budget per API key?
Plan and project caps are managed by Plugsky. Per-key budgets are an application-layer pattern: count usage by key, store the budget in your own database, and reject a request before sending it. Reconcile the counter with GET /v1/plugsky/usage daily.
Should I retry a 429 or a 402?
A 429 may be retried only after Retry-After and only within a retry budget. A 402 means the project budget is exhausted; retrying will not help until the cap is raised, so fail fast and alert finance.
How do I attribute spend to a team or customer?
Tag every request with the user or tenant field, use a separate key per project, and store model, prompt tokens, completion tokens and request ID with the tag. Then aggregate from logs and reconcile against the usage endpoint.
Sources
OpenAI spend limits guide for hard versus soft caps and 429 behaviour, checked 20 November 2026: developers.openai.com/api/docs/guides/spend-limits. Google Cloud Billing budgets documentation for threshold alerts and hard-stop patterns, checked 20 November 2026: cloud.google.com/billing/docs/how-to/budgets. FinOps Foundation Framework for budgeting, unit economics and reconciliation, checked 20 November 2026: finops.org/framework.
Reviewed 20 November 2026. Plan caps, project budget thresholds and status codes were checked against the Plugsky documentation on that date. Budget behaviour can change; verify the current terms in the dashboard and, for enterprise commitments, in the contract.