SOLWYN

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 responseSDK behavior
AllowedDispatch 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:

  1. The per-candidate cap: a positive caller or defaultParams cap (max_tokens, max_completion_tokens, Responses max_output_tokens, Anthropic max_tokens, Google config.maxOutputTokens, Bedrock inferenceConfig.maxTokens, or AI SDK maxOutputTokens), or else leaseOutputBoundDefault (default 4096).
  2. Plus reasoning outside the cap: Qwen's max_tokens leaves reasoning out, so its thinking_budget is added per candidate unless enable_thinking: false.
  3. Times the candidate count: OpenAI n or Google config.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.

ProviderField Solwyn adds
OpenAI and compatible chatmax_tokens, or max_completion_tokens for OpenAI o-series and GPT-5 models
Azure OpenAImax_completion_tokens, for every deployment
OpenAI Responsesmax_output_tokens
Anthropicmax_tokens
Googleconfig.maxOutputTokens
BedrockinferenceConfig.maxTokens (an uncapped command is sent as a rebuilt sibling command)
AI SDK middlewaremaxOutputTokens

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 automaticContinuation becomes false and unset automaticFunctionCalling becomes { 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: fallbacks are 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:

ChannelAllowed keys
OpenAI chat create params outside the typed openai setnone; Qwen may add enable_thinking and thinking_budget
OpenAI Responses and Anthropic messages params outside their typed setsnone
Google client-level httpOptions.extraBodynone (a per-request extraBody is rejected in every mode)
Bedrock additionalModelRequestFieldsthinking
AI SDK providerOptionsnone, at any depth
OpenAI and Anthropic client-level fetchOptions.bodynone (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();
}
reasonWhat triggers itHow to fix it
reasoning_without_budgetQwen 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_overrideA 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_loopGoogle 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_exceededThe 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_versionAn 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_containerGoogle config, or Bedrock inferenceConfig or additionalModelRequestFields, is not a plain object.Pass it as an object.
malformed_candidate_countn 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 Google chats. Use onUnmetered: "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: false is 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 fetch passed 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.0

Before 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:

  1. Computes a length-based estimated input-token count inside your process, and (0.3.0+) the call's output bound from its output caps.
  2. Checks the primary provider and model with Solwyn Cloud before any provider attempt.
  3. 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 OutputBoundUnenforceableError instead.
  4. Normalizes provider-reported usage and privately queues reservation settlement.
  5. 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:

  1. Preserve an applicable retained run stop or hard denial.
  2. If failOpen: true (the default), allow and record the local fallback estimate.
  3. If failOpen: false and no successful budget snapshot has ever been received, deny with denyReason: "no_prior_budget_limit".
  4. If failOpen: false and 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 with denyReason: "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.

OptionDefaultOrdinary check-path outage behavior
failOpentrueAllow after retained-authority checks and add the estimate to the local UTC-day bucket.
failOpenfalseEnforce 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:

  1. Ordinary outage decisions and their in-process UTC-day estimate bucket.
  2. The estimatedCost diagnostic on BudgetExceededError, 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_run denials 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 leaseUses the ordinary per-call check
Untagged text call inside run(...) or RunHandle.activate(...)Call outside a run
Model and fallback models covered by the grantAny call with client, run, or per-call tags
No applicable retained hard denial or run stopMedia and embedding calls
Lease subsystem enabled and Cloud marks the run eligibleModel 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

OptionDefaultPurpose
failOpentrueSelect the ordinary outage posture after retained-authority checks.
budgetMode"alert_only"Label SDK-local outage decisions only.
budgetCheckTimeout1Budget preflight timeout cap in seconds; at least 0.1. A lease attempt and its per-call fallback share it.
budgetCheckCacheTtl5Untagged, unscoped allow-cache lifetime in seconds; 0 disables it.
leaseEnabledtrueEnable eligible run-scoped token leases.
leaseOutputBoundDefault4096Output-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.

On this page