Feature · cost control

AI API spend controls and budget alerts

Know what a workspace, a project and a key can spend before the invoice arrives. Flat plans remove per-token billing; they do not remove the need for caps, alerts and reconciliation.

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-Warning at 80%, treat 429 as a quota or rate response, and treat 402 as a project budget stop. Reconcile your ledger against GET /v1/plugsky/usage every day.

Hard versus soft caps

ControlScopeAt the thresholdWho configures it
Plan daily capsWorkspace429 at 100%; reset 00:00 UTCPlan
Project dollar capProjectSoft alerts at 50/80/95%; 402 at 100%Dashboard
Warning headerHobby / StarterX-Plugsky-Quota-Warning at 80%Automatic
Application budgetKey, tenant or featureYour code rejects or downgradesYour service
Spend alertBilling or FinOpsEmail or webhook; traffic continuesDashboard / 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

StatusMeaningRetry?Action
429 + Retry-AfterRate or concurrency limitYes, after the delayBack off; shed low-priority work
429 quotaDaily request or token capNo until resetUpgrade or wait for 00:00 UTC
402Project budget cap reachedNoRaise the cap; alert finance
401 / 403Bad key or missing scopeNoFix credentials; do not rotate blindly
503Upstream unavailableYes, onceFailover; 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.

DimensionSourceUse
ProjectKey prefix or project IDChargeback, budget cap
Tenant / useruser fieldUnit economics, abuse detection
ModelResponse modelCost and quality comparison
Tokensusage blockCapacity planning
FeatureYour tag or routeProduct-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.