Spend refusals

For: Developers handling budget and quota refusals.

A budget, quota or job-tree limit refusal adds an oz0 object beside the error's type and message. Use the object's fields to decide whether to wait, request more budget or stop. The message is for people and its wording can change.

{
  "type": "error",
  "error": {
    "type": "oz0_quota_exceeded",
    "message": "team ml has spent $41.2000 of its $40.00 quota for October 2026; ask for more ...",
    "oz0": {
      "v": 1,
      "scope": "team",
      "scope_id": "team:ml",
      "window": "month",
      "resets_at": "2026-11-01T00:00:00Z",
      "limit_usd": 40,
      "spent_usd": 41.2,
      "call_estimate_usd": 0.0912,
      "limit_name": "monthly_usd",
      "can_wait": true,
      "raise": {
        "by": ["team_admin", "tenant_admin"],
        "command": "oz0 quota request team:ml --usd 10 --tenant acme --reason '...'"
      }
    }
  }
}

A client branches on the fields: it waits until resets_at (or for Retry-After), follows raise.request once a budget request is open, or stops.

Which refusals carry it

oz0_budget_unbounded (400) carries no object either: under reserve: strict the call's worst case cannot be bound, or under any mode it comes to more than a reservation can hold. No budget's figures are involved, and sending it again changes nothing.

oz0_budget_unavailable (503) carries no object: the budgets could not be read, which is an outage, not a refusal, and the call is sent again shortly. Neither does oz0_pool_cooling (429), a provider's cooldown, or oz0_killed.

Where it appears

A remote agent's session learns it from the answer to its usage reports, in the Oz0-Over-Budget-Detail header beside Oz0-Over-Budget.

Fields

Additions are fine: a client ignores fields it does not know. A renamed field, or one whose meaning changes, needs a new version, v: 2.

Who sees the numbers

A person's or a team's figures and name are shown only to a caller who may read that quota today: the person themselves, for their own quota, or someone whose role holds usage.read and whom works-council mode lets see that figure (a team of at least the tenant's threshold of people, a service identity, or anyone once an admin turned the mode off).

For anyone else the object keeps v, scope, window, resets_at, can_wait and raise without its command, sets withheld, and the message names neither the quota nor its figures:

{"v": 1, "scope": "team", "window": "month", "resets_at": "2026-11-01T00:00:00Z", "can_wait": true,
 "raise": {"by": ["team_admin", "tenant_admin"]}, "withheld": true}

Each surface filters for its own caller. The gateway answers the node that acts for a job, so its answer is filtered for the person who started the job's tree; the runtime API, MCP, A2A and AG-UI filter for whoever called them; a webhook's answer for the webhook's own identity (service:webhook/<flow>). A job tree's own budget, the tenant's budget and the tree's limits are not figures about people, and are shown to everyone who gets the refusal.

The audit trail's run.refused entry keeps the refusal as the limit wrote it, whoever was refused: its reason and refusal_detail name the quota that stopped the start or the call, with its figures, because the trail is for those who hold audit.read. The evidence record of a model call keeps the figures but never the name of a person or team: scope_id and raise.command are left out for person and team, as the record names only kinds of budget.

Retry-After

A refusal of a quota or of the tenant's month whose resets_at is within 24 hours carries Retry-After, in seconds until the reset: on the gateway's 402, on a webhook's 429, and in the metadata of StartJob's error. A client that honours it waits without code of its own. A tree's budget and its limits never reset, so their refusals never carry it. oz0_budget_busy keeps its own short Retry-After (two seconds), since what it waits for is calls that settle, not a reset.