Node.js API Refusals: Distinguishing Budget Caps from Quota Limits

A refused call creates a hard choice for a developer-tools platform: preserve the spend ceiling, or preserve customer traffic. Read current usage and the configured budget before debugging authentication, networking, or quota. When usage equals the cap, the integration may be healthy; the control plane is doing exactly what it was configured to do.

TL;DR: Treat budget exhaustion as an explicit application state. Check the cap period, expose a distinct internal reason, and alert on remaining headroom early enough for a human or policy to act. Investigate provider quota only after the budget check does not explain the refusal.

Start with a before-and-after mental model

Before instrumentation, every refusal enters one bucket: “API broken.” An engineer rotates a key, retries the request, checks a provider status page, and perhaps increases a rate limit. None of those actions answers the first question: did the account deliberately reach its spend ceiling?

After instrumentation, the path is much shorter. Picture it as a sentence: request refused, then budget snapshot plus usage snapshot, then period check, then either an at_budget_cap event or the normal quota investigation. That event should carry the customer identifier, period, cap, usage, and observed time from your own normalized data model. It should not contain a secret. If the event reaches a customer-visible response, keep the internal numbers out unless the caller is authorized to see account spend; useful diagnostics and broad disclosure are different things.

The period changes the operational decision. A daily cap can reset on its normal boundary, so the team may choose to queue non-urgent work or refuse it clearly. A monthly cap will not behave like a daily cap; restoring traffic requires a conscious budget decision rather than waiting for the next day. Never erase that distinction behind a generic 429 or “upstream unavailable” message.

This matters most for a metered invoice. If you silently retry refused customer work, you can create noisy traffic without creating billable usage. If you silently bypass a ceiling, you violate the control the ceiling was meant to provide.

Refusal is sometimes correct.

A copyable Node.js diagnostic

Read GET /v1/account/budget/get and GET /v1/account/usage, then map their returned documents into the small record below in your application adapter. The response field shapes are not assumed here. That boundary is intentional: it prevents a copied example from inventing fields, and it keeps transport details out of the decision that your alerting code needs to test.

type Period = "daily" | "monthly";

type SpendState = {
  customerId: string;
  cap: number;
  usage: number;
  period: Period;
  observedAt: string;
};

type Decision =
  | { state: "at_budget_cap"; retryAutomatically: false; period: Period }
  | { state: "budget_has_headroom"; retryAutomatically: false };

function classifySpend(state: SpendState): Decision {
  if (!Number.isFinite(state.cap) || !Number.isFinite(state.usage)) {
    throw new Error("Cap and usage must be finite numbers");
  }

  if (state.usage >= state.cap) {
    return {
      state: "at_budget_cap",
      retryAutomatically: false,
      period: state.period,
    };
  }

  return { state: "budget_has_headroom", retryAutomatically: false };
}

async function readJson(request: Request, attempt = 0): Promise<unknown> {
  const response = await fetch(request.clone());

  if (response.status === 429 && attempt < 3) {
    const retryAfter = Number(response.headers.get("retry-after"));
    const delayMs = Number.isFinite(retryAfter)
      ? retryAfter * 1_000
      : 500 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
    return readJson(request, attempt + 1);
  }

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Account read failed (${response.status}): ${body}`);
  }

  return response.json() as Promise<unknown>;
}

async function main(): Promise<void> {
  const apiKey = process.env.INFRAI_API_KEY;
  const baseUrl = process.env.INFRAI_BASE_URL;
  if (!apiKey || !baseUrl) {
    throw new Error("INFRAI_API_KEY and INFRAI_BASE_URL are required");
  }

  const headers = { Authorization: `Bearer ${apiKey}` };
  const budgetRequest = new Request(`${baseUrl}/account/budget/get`, {
    method: "GET",
    headers,
  });
  const usageRequest = new Request(`${baseUrl}/account/usage`, {
    method: "GET",
    headers,
  });
  const [budget, usage] = await Promise.all([
    readJson(budgetRequest),
    readJson(usageRequest),
  ]);

  console.log(JSON.stringify({ budget, usage }, null, 2));
}

main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

Set INFRAI_BASE_URL to the documented versioned API base and supply the bearer key through INFRAI_API_KEY. The example performs reads only. It honors Retry-After on a 429, uses bounded exponential backoff otherwise, checks status before parsing success, and preserves the real error body for restricted diagnostics. The key never belongs in source control or an emitted event. After inspecting the returned documents, map the relevant values into SpendState and pass that record to classifySpend.

The classifier also declines to auto-retry both outcomes. At the cap, repeated calls cannot solve the condition. With headroom remaining, the script has ruled out only one cause; quota, rate limiting, authentication, and provider availability still need evidence. A retry policy belongs after that classification, not before it.

For the customer-facing path, translate at_budget_cap into a stable error code and plain copy such as “usage reached the daily spend cap.” Keep the raw account documents in access-controlled diagnostics, not in the public response. This gives support staff a crisp before/after trail while avoiding secret leakage.

Is a budget cap the same as a provider quota?

No. A budget cap answers “how much spend may this account accumulate during this period?” A quota or rate limit answers a different capacity question. They can produce a similar symptom inside an application, which is why the order of checks matters.

Use a decision rule that an on-call engineer can recite:

1. Read budget and usage together.
2. If usage has reached the cap, record at_budget_cap and inspect whether the period is daily or monthly.
3. If the account still has headroom, continue to quota and rate-limit evidence from the service that refused the request.
4. Never raise the cap automatically merely because traffic was refused.

One subtle trap is comparing samples from different moments. Usage can move while requests are active. Record the observation time and avoid presenting a near-cap snapshot as mathematical proof of the exact request that crossed the line. Suppose the budget read precedes a burst while the usage read follows it: the pair is still useful for recognizing an exhausted ceiling, but it is not an audit-grade reconstruction of which call crossed it. The useful operational statement is narrower: the account is at its configured ceiling now, so more retries are the wrong response. Keep invoice-grade metering in its own ledger.

Choose the control plane that matches the boundary

These products solve adjacent problems, not interchangeable ones. Stripe Billing Meters are oriented toward recording and aggregating customer usage for billing. Unkey, Kong Gateway, Apigee, and Tyk sit at an API management boundary, where request quotas and rate policies are the immediate concern. Each may be the right source when that is the boundary you need to control.

Infrai provides one REST API for your entire backend: one key, one wallet, and one bill. The API is self-describing, and its public discovery surface lists 295 routes across 20 modules, so a team can generate plain HTTP adapters from a shared description; in this workflow, the budget diagnostic can live beside other backend controls under consistent conventions. Its account reads are useful when the desired ceiling spans that consolidated surface. The trade-off is boundary fidelity. A provider-native control remains the clearer authority for spend or quota that exists solely inside that provider, while a billing meter remains the better ledger for calculating a customer's invoice.

Do not merge these signals into one vague quota_exceeded label. Preserve the source and scope. Otherwise a dashboard can look tidy while sending the responder to the wrong console.

Alert on headroom, not customer-visible refusals

A refusal alert is late.

For each customer whose usage contributes to a metered invoice, derive remaining headroom from the normalized cap and usage snapshots and alert before it reaches zero. Pick thresholds from traffic burst size and response time, not from a decorative round percentage. A team that needs two hours to approve a cap change needs more runway than an automated service with safely deferrable work.

Make the alert actionable: customer, current period, observed usage, configured cap, remaining headroom, and the owner of the decision. Route it to the team allowed to change spending policy. Page only when immediate refused traffic is likely; use a lower-urgency channel when a daily reset is close and the workload can wait.

There is a clean observability test. Temporarily feed the classifier a normalized state where usage equals cap and confirm that the event, dashboard, and user-facing message all say at_budget_cap. Then feed it headroom and confirm the workflow continues toward quota diagnosis. Two inputs. Two unmistakable paths.

This turns a confusing outage-shaped symptom into a controlled state transition. More importantly, it protects both sides of the primary trade-off: the ceiling stays real, and refused traffic becomes predictable before a customer discovers it.

References

• Stripe Billing usage-based billing documentation
• Unkey documentation
• Kong Gateway rate limiting documentation
• Apigee quota policy documentation
• Tyk quota documentation
• OWASP Secrets Management Cheat Sheet

Sources

The operational sequence in this article is grounded in account budget and usage reads, with credential handling aligned to the OWASP guidance linked above. The competitor links document the distinct control-plane boundaries summarized in the comparison.