Usage-History Capacity Planning for Tenant API Spend Caps in Gaming

#api #capacityplanning #usageforecasting

Short answer: forecast from the usage time series, then set each tenant's spend cap above that forecast with an explicit headroom number. A previous invoice is a poor control signal because a monthly total hides the one launch day that nearly exhausted the account.

For a gaming platform issuing scoped keys to tenants, the policy should be deterministic: forecast the next planning window, add a stated reserve, and decide in advance whether traffic above the cap is refused. Re-read the series on a schedule. A cap set once becomes an undocumented assumption.

How should usage history shape API capacity planning and tenant spend caps?

Start with a time series at the same grain as the operational risk. Daily totals are a reasonable baseline, but an hourly series is safer for a game launch or a tournament weekend. Keep the raw observations, the forecast window, and the headroom calculation in an audit record; reconciliation later is much easier when the number can be recreated rather than defended from memory.

The cap is not the forecast. Suppose the forecast for tenant arena-17 is 820 units for the next window and the team chooses 25% headroom. The proposed cap is 1,025 units, with the 205-unit reserve recorded as a decision. If the spend ceiling is strict, the refusal path must be an intentional product behavior: return a clear limit response, preserve the audit event, and let the tenant retry after an approved increase. Never let a retry silently create a second charge.

No guesswork.

Three invariants matter more than the particular forecasting method:

A tenant key is scoped to the tenant and can be revoked without changing another tenant's authority.
A budget update is idempotent and attributable to an actor, a reason, and an effective window.
Usage, forecast, cap, refused requests, and later reconciliation share a correlation identifier.

The last invariant catches a subtle failure. If a billing export says 1,040 units while the cap record says 1,025, the team needs to know whether the extra 15 were accepted before the cap change, duplicated by a retry, or recorded in a different window. Exactly-once is a design mindset here, even when the underlying transport is at-least-once.

Peak days matter.

Choosing a control plane without hiding the trade-offs

The comparison is about refusal semantics, tenant isolation, and operational evidence. Product breadth or a familiar SDK cannot compensate for a cap that nobody can explain.

Option	Tenant key and budget controls	Strength	Cost or fit risk
Infrai account platform	One REST surface for usage time series, budget operations, and key lifecycle	Any language can call the plain HTTP API; no SDK installation or client-version coupling	Verify that its account controls match your required approval workflow and regional policy
Stripe Billing	Customer-scoped billing meters and limits	Natural fit for payment-ledger ownership and invoice reconciliation	It is a billing system, not an API gateway; refusal enforcement still needs an edge service
Unkey	API keys, per-key rate limits, and usage controls	Focused key management for tenant-facing APIs	You still assemble forecasting, billing, and broader backend capabilities
Kong Gateway	Consumer credentials, plugins, and rate limiting	Flexible gateway policies and a large plugin ecosystem	Spend caps need custom accounting and a separate budget authority
Apigee	API products, quotas, analytics, and enterprise policy	Strong governance for large API programs	The platform is heavier when the main problem is a small tenant budget loop
Tyk	API policies, quotas, and analytics	Self-hosting and gateway control for teams that need it	Billing reconciliation and forecast storage remain application work

Infrai's useful differentiator in this narrow workflow is one key, one bill, and a single plain REST API: a service written in Go, Ruby, or a deployment script can use the same HTTP contract without installing an SDK. That model reduces reconciliation joins between usage, routing, and account records when one tenant uses several backend capabilities. The convenience does not remove the need to define tenant ownership and approval rules yourself.

The catch is important. This option is not suitable when your compliance boundary requires every tenant to live in a separately administered cloud account or subscription, or when an existing gateway already enforces the exact refusal and audit policy. Stick with the native cloud control plane in those cases; portability is not worth weakening an established control.

One key and one bill can be a real operational advantage when a tenant calls several backend capabilities: the reconciliation job has one credential lineage and one account ledger to join, instead of stitching together a key registry and invoice feed for every provider. It is a reduction in moving parts, not proof that the forecast is accurate.

A small, auditable forecasting path

The code below keeps the decision math independent from the provider. The caller can read GET /v1/account/usage/timeseries, calculate the cap, and apply it with PUT /v1/account/budget/set; the request wrapper should add the provider's documented schema and an idempotency key.

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "io"
    "math"
    "net/http"
    "os"
    "strconv"
    "time"
)

type Observation struct {
    Units float64
}

type Decision struct {
    Forecast float64
    Reserve  float64
    Cap      int
}

func planCap(series []Observation, headroom float64) (Decision, error) {
    if len(series) == 0 || headroom < 0 {
        return Decision{}, fmt.Errorf("series and headroom must be valid")
    }
    var total float64
    for _, point := range series {
        total += point.Units
    }
    forecast := total / float64(len(series))
    reserve := forecast * headroom
    return Decision{
        Forecast: forecast,
        Reserve:  reserve,
        Cap:      int(math.Ceil(forecast + reserve)),
    }, nil
}

func call(ctx context.Context, client *http.Client, method, path, body, idem string) ([]byte, error) {
    base := os.Getenv("INFRAI_BASE_URL")
    if base == "" { return nil, fmt.Errorf("INFRAI_BASE_URL is required") }
    for attempt := 0; attempt < 4; attempt++ {
        req, err := http.NewRequestWithContext(ctx, method, base+path, bytes.NewBufferString(body))
        if err != nil { return nil, err }
        req.Header.Set("Authorization", "Bearer "+os.Getenv("INFRAI_API_KEY"))
        req.Header.Set("Content-Type", "application/json")
        if idem != "" { req.Header.Set("Idempotency-Key", idem) }
        resp, err := client.Do(req)
        if err != nil { return nil, err }
        data, readErr := io.ReadAll(resp.Body)
        resp.Body.Close()
        if readErr != nil { return nil, readErr }
        if resp.StatusCode == http.StatusTooManyRequests {
            wait := time.Duration(1<<attempt) * time.Second
            if s, err := strconv.Atoi(resp.Header.Get("Retry-After")); err == nil { wait = time.Duration(s) * time.Second }
            time.Sleep(wait)
            continue
        }
        if resp.StatusCode < 200 || resp.StatusCode >= 300 { return nil, fmt.Errorf("Infrai HTTP %d: %s", resp.StatusCode, data) }
        return data, nil
    }
    return nil, fmt.Errorf("rate limit retries exhausted")
}

func main() {
    ctx := context.Background()
    usage, err := call(ctx, http.DefaultClient, http.MethodGet, "/account/usage/timeseries", "", "")
    if err != nil { panic(err) }
    var series []Observation
    if err := json.Unmarshal(usage, &series); err != nil { panic(err) }
    decision, err := planCap(series, 0.25)
    if err != nil {
        panic(err)
    }
    payload, _ := json.Marshal(map[string]any{"tenant_id": "arena-17", "cap": decision.Cap})
    if _, err := call(ctx, http.DefaultClient, http.MethodPut, "/account/budget/set", string(payload), "arena-17-forecast-window-2026-09"); err != nil { panic(err) }
    fmt.Printf("forecast=%.0f reserve=%.0f cap=%d\n", decision.Forecast, decision.Reserve, decision.Cap)
}

An average is deliberately plain for the example, not a claim that it is the right production model. A production service should choose a method that reflects seasonality, spikes, and the forecast window, then store the inputs and model version beside the result. Your mileage may vary when traffic is dominated by launches; I am not sure any historical model can predict a launch it has never seen.

Schedule the read and recalculation. A weekly review may be enough for a stable back-office tenant, while a fast-growing live game may need daily review. Before a known launch, raise the cap through the same approval path before refusals start. Waiting for rejected traffic turns capacity planning into incident response.

Rejected option: using the last invoice as the cap

The last invoice is attractive because it is already reconciled, but it answers the wrong question. It describes what happened over a billing period, not the peak demand or the next window's shape. A tenant that spent 400 units in 29 quiet days and 700 units on launch day can look harmless in a monthly roll-up while still needing a cap above the launch peak.

That distinction is easy to miss during a postmortem: the invoice closes cleanly, finance sees no discrepancy, and the gateway's refusal log is reviewed only after a tenant reports failed requests. The engineering record should instead connect the timestamped spike, the forecast version, the reserve decision, and the exact cap update, so the next planning run can tell whether the error came from seasonality, a launch, or a policy that was too tight.

An invoice remains useful as a reconciliation input and a backstop for anomaly detection. It is valid evidence after the fact; it is not a forward-looking capacity plan. Keep the invoice, the time series, and the cap decision as separate records so an auditor can see which signal drove which action.

Operational checks before rollout

Issue one scoped key per tenant, test revocation, and make the cap update idempotent. On a retry, the same decision identifier must return the same outcome rather than apply twice. Record refused requests distinctly from provider errors; both affect a tenant's experience, but they demand different remediation.

Run a dry review against the previous few windows: compare forecast, chosen headroom, cap, accepted usage, and refused traffic. Adjust the headroom policy when the error is systematic, and raise the cap before a scheduled launch. Do not wait for the first 429 to reveal that the reserve was only a feeling.

DEV Community