TypeScript SDK Budgets
Enforce Cloud-authoritative budgets, choose an outage posture, and understand run-scoped token leases.
The TypeScript SDK obtains budget authority before it dispatches a tracked provider call. Configure limits and their live enforcement mode in Solwyn Cloud; the SDK enforces the decision Cloud returns.
Handle a hard denial
An ordinary hard budget denial becomes BudgetExceededError before provider dispatch. A denial
whose period is run_stopped for the active run becomes RunStoppedError instead. The budget
error carries the live or retained values that produced the decision:
import { BudgetExceededError, Solwyn } from "@solwyn/sdk";
import OpenAI from "openai";
const solwynApiKey = process.env.SOLWYN_API_KEY;
if (!solwynApiKey) throw new Error("SOLWYN_API_KEY is required");
const client = new Solwyn(new OpenAI(), {
apiKey: solwynApiKey,
project: process.env.SOLWYN_PROJECT,
});
try {
await client.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: "Summarize today's queue." }],
max_completion_tokens: 128,
});
} catch (error: unknown) {
if (!(error instanceof BudgetExceededError)) throw error;
console.error({
projectId: error.projectId,
budgetLimit: error.budgetLimit,
currentUsage: error.currentUsage,
estimatedCost: error.estimatedCost,
budgetPeriod: error.budgetPeriod,
mode: error.mode,
});
} finally {
await client.close();
}See typed errors for the complete error hierarchy.
Live mode comes from Solwyn Cloud
Every successful live budget check returns both an allowed verdict and a mode. That response is
authoritative for the call:
| Live Cloud response | SDK behavior |
|---|---|
| Allowed | Dispatch the provider call and retain any reservation for settlement. An allowed alert_only response at or above its limit also logs the budget warning, at most once every 30 seconds per client. |
Denied with mode: "alert_only" | Warn and dispatch the provider call. |
Denied with mode: "hard_deny" | Throw BudgetExceededError for an ordinary budget denial, or RunStoppedError for an active run_stopped denial; do not call the provider. |
Configure the project budget, scoped rules, and their modes in Solwyn Cloud. A hard-deny scoped rule can therefore block its matching call even when the project's general mode is alert-only.
budgetMode on the Solwyn constructor does not enable live hard-deny behavior. The SDK does not
send that option in BudgetCheckRequest; it is only the mode label attached to SDK-local outage
results. A local fail-closed result can deny even when that diagnostic label is "alert_only".
import { Solwyn } from "@solwyn/sdk";
import OpenAI from "openai";
const solwynApiKey = process.env.SOLWYN_API_KEY;
if (!solwynApiKey) throw new Error("SOLWYN_API_KEY is required");
const strictClient = new Solwyn(new OpenAI(), {
apiKey: solwynApiKey,
project: process.env.SOLWYN_PROJECT,
failOpen: false,
budgetMode: "hard_deny", // local outage-result label, not the live Cloud policy
});
await strictClient.close();The accepted values are "alert_only" and "hard_deny". See
configuration for environment-variable precedence and validation.
Effective mode
The live mode is the effective mode for the call. Solwyn Cloud reports "hard_deny" whenever
any enforcing cap applies to it: a hard-deny project, or, on an alert-only project, a hard-deny
scoped rule or a hard per-run cap that matches the call. That holds on allowed checks too, so the
SDK caps the output of an uncapped call under a scoped hard cap.
The 0.3.0 changelog lists a scoped hard-deny rule on an alert-only project as a known gap. Solwyn
Cloud now reports the effective mode on the check, so the SDK sees "hard_deny" there and caps the
call. No SDK change is needed.
What hard_deny bounds
SDK 0.3.0+. A hard-deny budget bounds a call's output, not only its input. Every text budget
check (chat, Responses, messages, Google, Bedrock Converse, and the AI SDK middleware) sends
estimated_output_bound, the most output tokens the call can produce. Solwyn Cloud reserves the
call's estimated input cost plus that many output tokens at the output rate of the call's
primary model, so a call whose bound does not fit the remaining budget throws
BudgetExceededError before dispatch. Settlement still charges actual cost and releases the rest
of the reservation. The bound limits output tokens; the reservation is still an estimate in
dollars, so a call can settle above it (see known limitations).
Before 0.3.0 the check priced a call's output as equal to its input. Later calls were still refused once the cap was reached, but one call with a large output cap could spend far past it.
Nothing changes for calls admitted in alert-only mode. The mode that counts is the effective mode on the check: on an alert-only project, a call that a hard-deny scoped rule or per-run cap applies to is admitted in hard-deny mode and gets everything in this section. The bound is sent in every mode, so alert-only reservations get more accurate, but the SDK never changes a request admitted in alert-only mode.
How the bound is chosen
For each configured failover hop, the SDK takes:
- The per-candidate cap: a positive caller or
defaultParamscap (max_tokens,max_completion_tokens, Responsesmax_output_tokens, Anthropicmax_tokens, Googleconfig.maxOutputTokens, BedrockinferenceConfig.maxTokens, or AI SDKmaxOutputTokens), or elseleaseOutputBoundDefault(default4096). - Plus reasoning outside the cap: Qwen's
max_tokensleaves reasoning out, so itsthinking_budgetis added per candidate unlessenable_thinking: false. - Times the candidate count: OpenAI
nor Googleconfig.candidateCount. Absent means 1.
The bound is the largest across hops. A bound above 100,000,000 is sent as 100,000,000. Media
checks do not send it. For example, max_completion_tokens: 500, n: 3 sends 1,500, and a capped
primary with an uncapped fallback sends 4,096. The same bound sizes run lease
reservations.
Uncapped calls get a cap under hard_deny
An unbounded call cannot honestly be held to a hard cap. So when a hard-deny check allows a text
call, or the call draws on a lease with a hard-deny posture, a request with no positive output cap
is sent with leaseOutputBoundDefault (default 4096) as its per-candidate cap. A zero, negative,
non-integer, or null cap is replaced. A positive cap is never changed. Set your own cap to choose a
different limit, or raise leaseOutputBoundDefault.
| Provider | Field Solwyn adds |
|---|---|
| OpenAI and compatible chat | max_tokens, or max_completion_tokens for OpenAI o-series and GPT-5 models |
| Azure OpenAI | max_completion_tokens, for every deployment |
| OpenAI Responses | max_output_tokens |
| Anthropic | max_tokens |
config.maxOutputTokens | |
| Bedrock | inferenceConfig.maxTokens (an uncapped command is sent as a rebuilt sibling command) |
| AI SDK middleware | maxOutputTokens |
BudgetCheckResult.hardDenyAdmitted records whether hard-deny authority admitted the call.
SDK-local outage decisions never add a cap: those calls reach the provider exactly as you built
them.
Under hard_deny, a call also makes one model generation:
- Google: unset
automaticContinuationbecomesfalseand unsetautomaticFunctionCallingbecomes{ disable: true }for the call. Both are SDK-local settings. As a backstop, every Google generation request is checked before it is sent: it must name the admitted model and carry a cap that fits the bound. A call that already received one successful generation response cannot send another; the next request fails before it is sent, the reservation is kept, and the call reports a possibly-succeeded error. - Anthropic:
fallbacksare refused. - OpenAI, Anthropic, and Bedrock metered calls have no internal generation loop.
- AI SDK multi-step runs (
stopWhen) check and cap every step separately.
Body extensions are allowlisted under hard_deny. Each channel may carry only keys Solwyn counts in the bound:
| Channel | Allowed keys |
|---|---|
OpenAI chat create params outside the typed openai set | none; Qwen may add enable_thinking and thinking_budget |
| OpenAI Responses and Anthropic messages params outside their typed sets | none |
Google client-level httpOptions.extraBody | none (a per-request extraBody is rejected in every mode) |
Bedrock additionalModelRequestFields | thinking |
AI SDK providerOptions | none, at any depth |
OpenAI and Anthropic client-level fetchOptions.body | none (a per-request fetchOptions.body is rejected in every mode) |
Any other key, including model, refuses the call. Empty extensions are fine.
When a call cannot be bounded
On a hard-deny admission, a call that could produce more output than its bound, and that the SDK
cannot cap, fails with OutputBoundUnenforceableError (code: "output_bound_unenforceable") and
the failover chain stops. The error is thrown only on a hard-deny admission, never on an alert-only
admission; an alert-only project can still see it on calls a scoped hard cap applies to.
Normally the refusal comes before the request reaches the provider. A lease-funded call hands its local lease reservation back. A per-call reservation in Solwyn Cloud is not released early: it stays held until it expires, so the refused call briefly holds budget it never spent. The Google backstop is the exception: it can refuse a second generation request after the first one succeeded, so that call has already produced a paid generation. It reports a possibly-succeeded error and keeps its reservation at the bound.
import { OutputBoundUnenforceableError, Solwyn } from "@solwyn/sdk";
import OpenAI from "openai";
const solwynApiKey = process.env.SOLWYN_API_KEY;
if (!solwynApiKey) throw new Error("SOLWYN_API_KEY is required");
const client = new Solwyn(new OpenAI(), {
apiKey: solwynApiKey,
project: process.env.SOLWYN_PROJECT,
});
try {
await client.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: "Draft the weekly report." }],
max_completion_tokens: 2048, // the bound Solwyn reserves under hard_deny
});
} catch (error: unknown) {
if (!(error instanceof OutputBoundUnenforceableError)) throw error;
// Fix the request; retrying it unchanged fails the same way.
console.error({
code: error.code,
provider: error.provider,
reason: error.reason,
hint: error.hint,
});
} finally {
await client.close();
}reason | What triggers it | How to fix it |
|---|---|---|
reasoning_without_budget | Qwen with thinking not turned off and no positive thinking_budget. An xAI model without non-reasoning in its id, because xAI caps leave reasoning out and take no budget. Qwen or an xAI reasoning model through the AI SDK. An AI SDK reasoning effort other than none on a provider other than OpenAI or Azure OpenAI. A qwen*, qwq* or grok* model on a detected provider with no reasoning rule of its own. | Set a positive thinking_budget, set enable_thinking: false, or use a non-reasoning model. If your gateway counts reasoning inside the cap, set the provider explicitly. |
unsupported_override | A body extension carries a key outside the allowlist above, model included. A Google request that names a model other than the admitted one. | Remove the key, and set output limits with the request's own cap parameters. |
multi_generation_loop | Google automaticContinuation or an enabled automaticFunctionCalling config, Anthropic fallbacks, or a second Google generation request after a successful one. | Turn the loop off for the call, or run the loop yourself so Solwyn checks each generation. |
bound_exceeded | The final request can still produce more than its bound, for example a cap above 100,000,000. | Set the output cap and candidate count on the call itself. |
azure_api_version | An uncapped Azure OpenAI call on an api-version older than 2024-09-01. | Set max_tokens or max_completion_tokens on the call, or use a newer api-version. |
malformed_cap_container | Google config, or Bedrock inferenceConfig or additionalModelRequestFields, is not a plain object. | Pass it as an object. |
malformed_candidate_count | n or candidateCount is not a positive integer. | Set a positive integer, or leave it unset. |
See typed errors for the error's fields.
Known limitations
- The reservation is in dollars at the primary model's rate. Admission prices the primary model. If a fallback hop serves the call on a more expensive model, settlement charges that model's rate, so the call can spend more than it reserved even though its output stays within the bound. On a tight hard cap, keep fallbacks no more expensive than the primary.
- Input tokens are estimated from text length, so the input half of a reservation can be low.
- A refused call's Cloud reservation is held until it expires. Only local lease reservations are handed back on a refusal.
- Untracked surfaces have no budget check, so a hard cap does not cover them. These include
tool runners (
runTools,toolRunner) and Googlechats. UseonUnmetered: "raise"to refuse them. See providers. - Reasoning is treated as inside the cap except for Qwen and xAI. OpenAI, Azure OpenAI, Anthropic, Gemini, and Bedrock document this. DeepSeek, Groq, Mistral, Z.ai, Perplexity, and Fireworks are treated the same way, but their docs do not say so explicitly.
- A Qwen model that thinks even with
enable_thinking: falseis bounded without its reasoning. - The Qwen and xAI rules apply to OpenAI-dialect chat and the AI SDK. A Qwen model reached
through another wire format, such as a Bedrock
qwen.*model or an Anthropic SDK client pointed at DashScope, follows that dialect's rules. - Typed params whose effect on output length is unverified are allowed, for example Responses
context_management(compaction). - If the Google backstop ever fires, it fires after a paid generation, and that generation's usage is not reported. The reservation is kept at its bound and the error is marked possibly succeeded.
- Code that rewrites a request after Solwyn checks it is out of reach: a custom
fetchpassed to a provider client, or Bedrock middleware.
Upgrading
Install @solwyn/sdk 0.3.0 or later. 0.4.0 also needs a solwyn_sk_ API key and a project;
see the changelog.
npm install @solwyn/sdk@0.4.0Before you upgrade, check every call a hard cap governs (a hard-deny project, or a hard-deny scoped rule or per-run cap on an alert-only project): uncapped calls must live with a 4096-token cap (or set explicit caps), and no request may depend on body-extension keys, Google automatic function calling, or Qwen thinking without a budget. Older SDKs keep working. They send no output bound, so Solwyn Cloud prices their calls the old way, and one call can still overshoot a hard cap.
Admission and settlement
For an ordinary tracked text call, the SDK:
- Computes a length-based estimated input-token count inside your process, and (0.3.0+) the call's output bound from its output caps.
- Checks the primary provider and model with Solwyn Cloud before any provider attempt.
- Dispatches only if the result allows it. Under a hard-deny admission, an uncapped request gets
the default cap first, and a request that cannot be bounded throws
OutputBoundUnenforceableErrorinstead. - Normalizes provider-reported usage and privately queues reservation settlement.
- Queues a content-free metadata event. A blocked call is reported as
budget_denied.
A caller's request AbortSignal also cancels the budget preflight; cancellation rejects without
being treated as a control-plane outage, and an already-aborted request skips budget I/O. With
less than 50 milliseconds left on the shared preflight deadline, the SDK skips network I/O,
applies local policy, and logs budget.preflight_skipped_deadline.
Settlement is automatic; there is no public confirmation method. Buffered calls settle after their
response is available. Streams settle exactly once when they end or are abandoned; see
streaming. Await client.close() so queued confirmations and events get
a bounded final flush.
Solwyn Cloud owns provider and model pricing. The SDK reports token counts and media quantities; it does not calculate the actual cost of successful calls.
Untagged calls outside a run can reuse an allowed check for the same provider/model/fallback/modality
chain and the same output bound for up to budgetCheckCacheTtl seconds (5 by default), so an
allow for a small bound never admits a larger one. Run-scoped and tagged checks bypass that cache.
Denials are never cached.
When the budget service is unreachable
The ordinary per-call path evaluates outage authority in this order:
- Preserve an applicable retained run stop or hard denial.
- If
failOpen: true(the default), allow and record the local fallback estimate. - If
failOpen: falseand no successful budget snapshot has ever been received, deny withdenyReason: "no_prior_budget_limit". - If
failOpen: falseand a snapshot exists, compare this process's current UTC-day local estimate bucket plus the new estimate with the last-known Cloud budget limit. Allow and accrue within the limit; otherwise deny withdenyReason: "local_budget_exceeded".
failOpen is consulted only after stronger authority. Setting it to true cannot reopen a hard
denial the SDK has already received for the applicable scope.
| Option | Default | Ordinary check-path outage behavior |
|---|---|---|
failOpen | true | Allow after retained-authority checks and add the estimate to the local UTC-day bucket. |
failOpen | false | Enforce against the last-known limit; deny when no prior limit exists. |
budgetMode | "alert_only" | Label SDK-local outage results; it does not replace the live Cloud mode. |
The fixed local estimate has exactly two uses
The SDK multiplies estimated input tokens by $0.00003 per token in exactly two places:
- Ordinary outage decisions and their in-process UTC-day estimate bucket.
- The
estimatedCostdiagnostic onBudgetExceededError, including an error produced by a live Cloud denial.
That constant is not a provider price, does not select routes, and does not settle successful calls. Cloud remains authoritative for real provider/model pricing.
Retained authority
A semantically valid hard denial remains authoritative during a later outage:
- Project-period authority applies across calls on the client.
agent_rundenials and run stops apply only to the exact run ID.- A tag-period denial is enforced for the checked tag selector but is not retained as future outage authority, because tags can change on the next call.
- A later applicable Cloud allow can clear older retained budget authority. Run stops have their own exact-ID lifecycle; see runs.
A response containing a run-control directive for a different run is treated as contract drift. For
an otherwise ordinary allow or budget denial, the SDK enforces that call's verdict without retaining
the tainted composite as future authority. A foreign run_stopped response is not trusted as a stop
and enters the configured outage path.
Run-scoped token leases
With leaseEnabled: true (the default), an eligible text call inside a Node run can reserve tokens
from local, bounded authority rather than perform a blocking budget check for every call:
import { Solwyn } from "@solwyn/sdk";
import { run } from "@solwyn/sdk/node";
import OpenAI from "openai";
const solwynApiKey = process.env.SOLWYN_API_KEY;
if (!solwynApiKey) throw new Error("SOLWYN_API_KEY is required");
const client = new Solwyn(new OpenAI(), {
apiKey: solwynApiKey,
project: process.env.SOLWYN_PROJECT,
});
try {
await run("nightly-summary", async () => {
await client.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: "Summarize the first batch." }],
max_completion_tokens: 128,
});
await client.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: "Summarize the second batch." }],
max_completion_tokens: 128,
});
});
} finally {
await client.close();
}The first eligible call requests a grant. Later calls reserve estimated input tokens plus a
structural output bound from that grant. If no usable output cap is present, the reservation uses
leaseOutputBoundDefault (4096). Renewal is demand-driven, generation-fenced, and detached from
the call path. When a run finishes, its remaining authority is surrendered through one bounded
dispatcher per client, with at most four requests in flight and 64 waiting. A surrender that is
refused, overflows the queue, or passes its deadline is dropped and reported in an aggregated
lease.surrenders_dropped warning; the unused tokens then return when the lease expires.
close() drains outstanding surrenders within a separate one-second budget and logs any it could
not finish in lease.close_release_summary.
Lease eligibility is deliberately narrow:
| Uses a run lease | Uses the ordinary per-call check |
|---|---|
Untagged text call inside run(...) or RunHandle.activate(...) | Call outside a run |
| Model and fallback models covered by the grant | Any call with client, run, or per-call tags |
| No applicable retained hard denial or run stop | Media and embedding calls |
| Lease subsystem enabled and Cloud marks the run eligible | Model chain not yet covered by the grant, lease-ineligible run, or leaseEnabled: false |
When a per-call check allows a call whose model chain the lease does not cover, the SDK renews the lease in the background to cover that chain, and later calls on it use the lease. Widening to a more expensive model re-prices the lease, so every model's token grant shrinks. Denied, unreachable, tagged, and media calls never widen a lease. If Cloud refuses a grant with HTTP 409 or answers a renewal as ineligible, the run falls back to per-call checks for at most 150 seconds; after an ineligible renewal the SDK releases the lease and acquires a new one. Models that a widening renewal was refused for keep per-call checks for the rest of the run.
The grant is denominated in tokens, not dollars, and carries Cloud-selected posture and bounded
headroom for outages. While the grant is live, local reservations continue from its remaining
tokens. If the grant is exhausted while Cloud is reachable, the call returns to the per-call check.
During an outage, the holder can draw from the grant's headroom share; after that, the posture
carried by the grant decides whether hard-deny blocks or alert-only continues. After the lease
deadline, the grant's unreachable posture determines whether calls proceed uncounted for later
renewal reporting or enforce against the last-known share. Calls admitted against the outage share
or after lease expiry accrue the fixed local estimate in the current UTC-day bucket, and a
fail-open lease posture never relaxes a client configured with failOpen: false.
Tags stay on the live check path
Tags are explicit attribution labels supplied by your application. The SDK never infers them from prompts or responses. Keep them content-free—use stable labels such as tenant IDs, workflow names, or environments, and never put prompts, responses, personal data, or secrets in them.
Client, run, and per-call tag layers are merged for the call. The merged snapshot is sent on the
budget check so tag-scoped rules stay authoritative, and solwyn_tags is removed from intercepted
requests before provider dispatch. Because lease grants do not carry per-call tag authority, every
tagged call bypasses the run lease and performs the ordinary per-call check.
See runs and tags for merge precedence, validation, and detached run handles, and privacy for the outbound metadata boundary.
Relevant options
| Option | Default | Purpose |
|---|---|---|
failOpen | true | Select the ordinary outage posture after retained-authority checks. |
budgetMode | "alert_only" | Label SDK-local outage decisions only. |
budgetCheckTimeout | 1 | Budget preflight timeout cap in seconds; at least 0.1. A lease attempt and its per-call fallback share it. |
budgetCheckCacheTtl | 5 | Untagged, unscoped allow-cache lifetime in seconds; 0 disables it. |
leaseEnabled | true | Enable eligible run-scoped token leases. |
leaseOutputBoundDefault | 4096 | Output-token bound for a request without a usable cap, on the lease and per-call paths; also the cap added to such a request on a hard-deny admission. |
Use offline testing to exercise hard denials, outages, leases, and run-stop paths without Cloud or provider network traffic.