# How to set a client-side spend budget that stops SDK calls

> Stop a client from starting calls once its spend reaches a limit, and reserve each call's price where a burst or a restart must not overshoot it.

Source: https://voxgig.com/howto/set-a-spend-budget-that-stops-calls

- Audience: platform-team
- Level: advanced
- Languages: go, typescript
- Verified: 2026-11-20
- Published: 2026-11-19

## Short answer

Set `budget` and `onBudget: 'deny'` on the `cost` feature of an sdkgen client, and it refuses each call with `cost_budget` once the spend so far reaches the limit. That check is a cutoff, so ten concurrent calls against a budget of five all go out. To hold the limit under a burst, reserve each call's price in a `PrePoint` hook before it is sent. Keep the running total in a file so a restarted worker cannot spend it again.

---
## You will need

Node 22 or later, a client for a paid API, and the provider's price list. Verified 2026-11-20
against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, and `@voxgig/sdkgen` 4.44.3. The client and
its rate table come from
[attribute API cost per operation and per caller in an SDK](/howto/attribute-api-cost-per-operation-and-caller).
The provider is a stand-in on the loopback interface that logs every request reaching it. A place
lookup costs 1 credit and a search costs 5, and a 5XX response is not billed.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [AWS Budgets alert](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) | One view of spend across every process, client, and team | Its data updates up to three times a day, so it acts hours after the money is gone | A loop has to be stopped within seconds |
| [Go mutex-guarded counter](https://pkg.go.dev/sync#Mutex) | A hand-written Go client whose goroutines share one budget | The gate, the pricing function, and the persistence are all yours to write and test | The client is generated and already has a hook for this |
| [Kiota middleware handler](https://learn.microsoft.com/en-us/openapi/kiota/middleware) | A Kiota client, where a handler after the retry handler checks every attempt | It sees a concrete URL, so pricing needs a route matcher you maintain | You want a limit without writing a handler |
| [sdkgen `cost` feature budget](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md#the-budget) | An sdkgen client that should stop a sequential loop with two options | It checks spend so far, so a burst overshoots and a restart begins again from zero | Calls run concurrently, or the worker can crash-loop |
| [Speakeasy SDK hooks](https://www.speakeasy.com/docs/sdks/customize/code/sdk-hooks) | A Speakeasy SDK on a Business or Enterprise plan, with a hook file regeneration keeps | Hooks are limited to those plans, and the counter and price table are yours | Your plan has no hooks |

Voxgig maintains sdkgen. It is one of five options here, not the recommendation.

A client-side budget acts at once and costs nothing to run, but it knows only its own process.
sdkgen's takes two options, but it is a cutoff on spend already counted. A Kiota handler or a
Speakeasy hook can check each attempt, at the price of writing the counter. AWS Budgets sees every
process, but hours late.

## Set the budget on the cost feature

`budget` is a spend limit in the feature's currency, and `onBudget: 'deny'` turns it from a
warning into a refusal.

```js title="demo.mjs"
// The provider's price list in credits, keyed '<entity>.<op>'.
export const RATES = { 'place.list': 5, 'place.load': 1, 'route.create': 20 }
export const LIMIT = 5

/** A client whose cost feature refuses a call once the budget is spent. */
export function withCostBudget(base, more = {}) {
  return new GeodeskSDK({
    base,
    feature: {
      cost: { active: true, currency: 'credits', rates: RATES, budget: LIMIT, onBudget: 'deny' },
      ...more,
    },
  })
}
```

```bash
node demo.mjs
```

```text output
cost feature budget of 5 credits, lookups at 1 credit, one at a time
  lookup 1  ok
  lookup 2  ok
  lookup 3  ok
  lookup 4  ok
  lookup 5  ok
  lookup 6  refused, code cost_budget
  lookup 7  refused, code cost_budget
  client._cost.budget {"limit":5,"spent":5,"remaining":0,"exceeded":true}
  requests that reached the provider: 5
ten lookups at once against a budget of 5
  cost feature budget  10 reached the provider, 0 refused, 10 credits spent
  reserving guard       5 reached the provider, 5 refused with budget_exceeded, 5 credits committed
one search at 5 credits, admitted with nothing spent, then answered 503 three times
  cost feature budget   3 attempts sent after one check, 15 credits counted
```

One call at a time, the sixth lookup is refused before an endpoint is resolved, and it sends
nothing. The error is the SDK's own class with `code` set to `cost_budget`, and
`client._cost.budget` reports the limit, the spend, and what remains. Without `onBudget: 'deny'`
the feature sets `exceeded` and lets the call through.

The other two blocks are the limits of that check. It asks whether the budget is already spent,
never whether this call would pass it, so ten calls that start together all find nothing spent.
sdkgen's reference says as much: a cutoff, not a hard cap.[^1] The retries of an admitted call
are not checked either, and a call made through `client.direct()` is counted but never refused.

## Reserve each call's price before it is sent

To hold the limit under a burst, take the price out of the budget before the call leaves. The
check and the reservation are one synchronous step.

```js title="budget.mjs"
  reserve(cost) {
    if (!Number.isFinite(cost) || cost < 0) throw new RangeError(`not a cost: ${cost}`)
    if (this.#committed + cost > this.#limit) throw new BudgetExceededError(this.#limit, this.#committed, cost)
    // Save first: if the store fails, the call is refused and nothing is half-recorded.
    this.#store.save(this.#committed + cost)
    this.#committed += cost
  }
```

A feature passed in the client's `extend` option runs that at `PrePoint`, the first stage of
every operation.

```js title="budget.mjs"
export function reserving(budget, rates) {
  return {
    name: 'budget',
    PrePoint(ctx) {
      const op = `${ctx.entity?.name}.${ctx.op?.name}`
      try {
        if (!Object.hasOwn(rates, op)) throw Object.assign(new RangeError(`no rate for ${op}`), { code: 'budget_unpriced' })
        budget.reserve(rates[op])
      } catch (cause) {
        // Putting an error in out.point is how a PrePoint hook refuses a call.
        // The caller receives the SDK's own error class, carrying this code.
        const err = ctx.error(cause.code ?? 'budget_error', cause.message)
        ctx.out.point = err
        return err
      }
    },
  }
}
```

With `extend: [reserving(budget, RATES)]`, five of the ten calls reached the provider and five
were refused with `budget_exceeded`. JavaScript runs the hook without yielding, so a second call
cannot pass the check before the first reservation lands. The guard never gives a reservation
back, so a call that fails still counts as spent, and an operation with no rate is refused. Both
choices err toward stopping early.

## Keep the total across a restart

Both totals so far live in memory, so a worker that crashes and restarts gets a fresh budget each
time. The cost feature's options include no starting total, so its budget cannot be carried over.
The guard's can: a store that writes the total to a file closes the gap for one worker.

```js title="budget.mjs"
    save(total) {
      // Write beside the file and rename, so a crash mid-write leaves the old total.
      writeFileSync(`${path}.tmp`, JSON.stringify({ committed: total }))
      renameSync(`${path}.tmp`, path)
    },
```

```bash
node restart.mjs
```

```text output
a worker with a budget of 5 credits, started three times, 8 lookups per run
  cost feature budget, total in memory 15 lookups reached the provider
  reserving guard, total in memory     15 lookups reached the provider
  reserving guard, total in a file      5 lookups reached the provider
```

The rename replaces the file in one step.[^2] The store costs a file write per admitted call, and
it refuses to start from a file it cannot read as a total. It serves one writer at a time: two
live processes sharing the file overwrite each other, and need a store with an atomic increment.
If you keep the total in memory, say plainly that the budget is per process.

## Stop calls at the same budget in Speakeasy and Kiota

Speakeasy's [extension list](https://www.speakeasy.com/docs/speakeasy-reference/extensions) names
no budget option. Its mechanism is an
[SDK hook](https://www.speakeasy.com/docs/sdks/customize/code/sdk-hooks): implement
`BeforeRequestHook`, register it in `src/hooks/registration.ts`, which is generated once and never
overwritten, and throw from `beforeRequest` to stop the request. The hook context carries
`operationID`, the key for a price table, and `afterSuccess` and `afterError` receive the response
to count. In a
[published client](https://github.com/mistralai/client-ts/blob/main/src/lib/sdks.ts) that
Speakeasy generated, `beforeRequest` runs inside the retry loop, so a check there covers every
attempt. The caller of that client receives an `UnexpectedClientError` whose `cause` is the error
the hook threw. Hooks are available to Business and Enterprise users only.

Kiota's [middleware page](https://learn.microsoft.com/en-us/openapi/kiota/middleware) lists no
budget handler either, so the seam is a handler of your own. Spliced into the default chain one
place after `RetryHandler`, it reserves before each attempt and gives the credit back only for a
response the provider did not bill. An attempt that throws keeps its reservation, because the
provider may have billed a request whose response was lost.

```js title="kiota-budget.mjs"
  async execute(url, requestInit, requestOptions) {
    const route = routeOf(requestInit.method, new URL(url).pathname)
    if (!this.prices.has(route)) throw new RangeError(`no price for ${requestInit.method} ${new URL(url).pathname}`)
    const cost = this.prices.get(route)
    // Throws BudgetExceededError, and nothing is sent.
    this.budget.reserve(cost)
    // If this throws, the reservation stays: the provider may have billed a
    // request whose response was lost.
    const response = await this.next.execute(url, requestInit, requestOptions)
    if (!billable(response.status)) this.budget.release(cost)
    return response
  }
}

/** A Kiota client for the provider with the budget handler in its middleware chain. */
export function makeClient(api, budget) {
  const handlers = MiddlewareFactory.getDefaultMiddlewares()
  handlers.splice(handlers.findIndex((h) => h instanceof RetryHandler) + 1, 0, new BudgetHandler(budget, PRICES))
  const adapter = new FetchRequestAdapter(new AnonymousAuthenticationProvider(), undefined, undefined, KiotaClientFactory.create(undefined, handlers))
  adapter.baseUrl = api.base
  return createGeodeskClient(adapter)
}
```

```bash
node kiota-budget.mjs
```

```text output
Kiota client, ten lookups at once against a budget of 5
  5 reached the provider, 5 refused with BudgetExceededError, 5 credits committed
one search at 5 credits, answered 503, 503, 200
  3 attempts sent, each one checked, 5 credits committed
```

The handler's own error reaches the caller unchanged. It sees a concrete URL, so it prices
through a route matcher, and Kiota's TypeScript target is a preview by its own output.

## Guard a hand-written Go client with a mutex

In Go the check and the reservation need a lock, because goroutines run in parallel.

```go title="budget.go"
func (b *Budget) Reserve(cost int) error {
	if cost < 0 {
		return fmt.Errorf("not a cost: %d", cost)
	}
	b.mu.Lock()
	defer b.mu.Unlock()
	if b.committed+cost > b.Limit {
		return &BudgetError{b.Limit, b.committed, cost}
	}
	b.committed += cost
	return nil
}
```

```bash
go run budget.go
```

```text output
ten goroutines, one lookup each, against a budget of 5 credits
  5 reached the provider, 5 refused with *BudgetError, 5 credits committed
```

A [`RoundTripper`](https://pkg.go.dev/net/http#RoundTripper) calls `Reserve` before it sends, and
`Release` only when a response arrives with a status the provider does not bill. A transport error
keeps the reservation, for the same reason as in the Kiota handler. The gate closes the request
body when it refuses, which the interface requires of every implementation, and callers match the
`*BudgetError` with `errors.As`.

```go title="budget.go"
// RoundTrip refuses the request with a *BudgetError, or sends it on.
func (g *Gate) RoundTrip(req *http.Request) (*http.Response, error) {
	cost := g.Price(req)
	if err := g.Budget.Reserve(cost); err != nil {
		// A RoundTripper closes the request body even when it sends nothing.
		if req.Body != nil {
			req.Body.Close()
		}
		return nil, err
	}
	resp, err := g.Next.RoundTrip(req)
	// An error is no proof that nothing was billed: the provider may have
	// charged for a request whose response was lost. Only a response with an
	// unbilled status gives the credit back.
	if err == nil && !billable(resp.StatusCode) {
		g.Budget.Release(cost)
	}
	return resp, err
}
```

## Check it worked

Run the suite. It counts requests at the stand-in, never at the client under test.

```bash
node --test budget.test.mjs
```

```text output
1..20
# tests 20
# suites 0
# pass 20
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

`# pass 20`. Three tests run ten calls at once against a budget of five and count requests at the
stand-in: `10` for the cost feature's budget, `5` for the reserving guard, and `5` for the Kiota
handler. One loses three responses that the stand-in had billed, and counts one request against a
budget of one. The last test runs the Go suite, which has the same test.

## When it goes wrong

The guard never runs. The generated README shows an `extend` feature as an object with a `hooks`
map, but this runtime calls methods named after the stage on the object itself. Put `PrePoint` on
the object.

Every call is refused after a deploy. The file store could not read its file as a total, so the
budget refused to start at zero. Repair or remove the file on purpose.

Spend passes the limit with no call refused. The calls went through `client.direct()`, or they
ran in another process. Neither reaches this client's `PrePoint`.

The provider bills more than the committed total. A response was lost after the provider billed
the request, and a guard that refunds on any error gave that credit back. Refund only on a status
the provider does not bill, as the Kiota handler and the Go gate do.

## When not to do this

Do not present a client-side budget as a cap on the bill. Requests in flight complete, retries
already admitted fire, and workers in other processes keep their own totals. For a limit across
all of them, use a provider-side control, and accept that AWS Budgets reports hours late.[^3]

Do not rely on sdkgen's `budget` where calls run concurrently or attempts must be checked one by
one. A Kiota handler or a Speakeasy hook sits inside the retry loop and sees each attempt, which
sdkgen's `PrePoint` check does not.

Do not share one sdkgen Go client's budget across goroutines. In the Go target generated from the
same project, ten goroutines all got through a budget of five, and the race detector reported data
races in `feature/cost_feature.go`.

Do not point two live processes at one budget file.

## Related how-tos

- [Attribute API cost per operation and per caller in an SDK](/howto/attribute-api-cost-per-operation-and-caller)

- [Add a circuit breaker to an outbound HTTP client](/howto/add-a-circuit-breaker-to-an-http-client)

- [Kill-switch one vendor integration without a deploy](/howto/kill-switch-a-vendor-without-a-deploy)

- [Choose the pipeline stage where an SDK behavior should run](/howto/map-a-behaviour-to-a-pipeline-stage)

- [Wrap an SDK transport in a middleware chain](/howto/wrap-an-sdk-transport-with-middleware)

## Last verified

Verified 2026-11-20 against Node 22.23.5, Go 1.24.7, `@voxgig/create-sdkgen` 0.31.9,
`@voxgig/sdkgen` 4.44.3, and Kiota 1.38.0 with its TypeScript runtime at 1.0.0-preview.114. Every
output block is what the command preceding it printed. Speakeasy was not run; its hook comes from
its documentation and from the source of a client it generated. AWS Budgets was not run. The Go
target of the sdkgen project was generated and run under the race detector once, and is not
committed.

[^1]: The [features reference](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md#the-budget)
puts it in bold: it is a cutoff, not a hard cap, and the difference matters. Its own example sets
a budget of 2 and a call priced at 5. The first call is admitted with nothing spent, and the
total stands at 5 before anything is refused. The advice that follows is to size the budget one
call's worth below the number you cannot exceed.

[^2]: The [rename(2) manual page](https://man7.org/linux/man-pages/man2/rename.2.html) says that
an existing target is atomically replaced, so that no other process finds it missing. The same
paragraph concedes a window in which both names refer to the file. A budget can live with two
names for its total. It cannot live with none.

[^3]: The AWS Budgets [user guide](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html)
says its information is updated up to three times a day, typically 8 to 12 hours after the
previous update. A note in that guide adds that costs may pass the notification threshold
before AWS Budgets can notify you.