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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| AWS Budgets alert | 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 | 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 | 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 | 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 | 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.
// 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.
Related how-tos
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
-
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
-
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
-
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