How-to › Ship an SDK

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.

Audience
Platform team
Level
advanced
Topic
Compose runtime features in an SDK
Languages
Go and TypeScript
Verified

Read first: Attribute API cost per operation and per caller in an SDK

A retry storm in one worker spends a week of API credits before breakfast. The provider’s budget alert lands hours later, because its billing data refreshes a few times a day. The client that sent every one of those calls held the running total the whole time, with no instruction to stop at any figure.

What you get

You will end up with a client that refuses to start a call once its spend reaches a limit, proven by a test that counts the calls reaching the transport. This is for you if one runaway worker can spend real money.

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. 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

ApproachWhen it fitsWhat it costs youWhen to pick something else
AWS Budgets alertOne view of spend across every process, client, and teamIts data updates up to three times a day, so it acts hours after the money is goneA loop has to be stopped within seconds
Go mutex-guarded counterA hand-written Go client whose goroutines share one budgetThe gate, the pricing function, and the persistence are all yours to write and testThe client is generated and already has a hook for this
Kiota middleware handlerA Kiota client, where a handler after the retry handler checks every attemptIt sees a concrete URL, so pricing needs a route matcher you maintainYou want a limit without writing a handler
sdkgen cost feature budgetAn sdkgen client that should stop a sequential loop with two optionsIt checks spend so far, so a burst overshoots and a restart begins again from zeroCalls run concurrently, or the worker can crash-loop
Speakeasy SDK hooksA Speakeasy SDK on a Business or Enterprise plan, with a hook file regeneration keepsHooks are limited to those plans, and the counter and price table are yoursYour 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.

// 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,
    },
  })
}
node demo.mjs
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.

  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.

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.

    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)
    },
node restart.mjs
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 names no budget option. Its mechanism is an SDK hook: 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 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 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.

  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)
}
node kiota-budget.mjs
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.

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
}
go run budget.go
ten goroutines, one lookup each, against a budget of 5 credits
  5 reached the provider, 5 refused with *BudgetError, 5 credits committed

A 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.

// 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.

node --test budget.test.mjs
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.

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.

Footnotes

  1. The features reference 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. ↩︎ Back to text

  2. The rename(2) manual page 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. ↩︎ Back to text

  3. The AWS Budgets user guide 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. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.