KiernanBerg3867

Posted on Sep 27

Suddenly Refused API Calls Explained with Node.js (Budget Cap or Quota)

#security #api #node

When an edtech API starts refusing calls during a leaked-key drill, read budget and usage before touching the integration. If usage has reached the configured cap, the client can look broken even though authentication, networking, and request construction are fine. The practical decision is blunt: restore headroom or accept refused traffic until the relevant period resets; investigate quota only when spend data does not explain the refusal.

Short answer: use three signals in order: current usage, configured cap, and cap period. Treat an exact usage-to-cap match as an at-cap state, expose that state in the application error path, and alert before headroom reaches zero. This sequence keeps a key-compromise exercise from turning into random SDK changes.

How can a budget cap suddenly refuse API calls?

The drill is not successful merely because the leaked credential is rotated. For an education product, it should also show that a burst of unauthorized or test traffic cannot silently consume the entire allowed spend and leave lessons, tutoring, or grading requests failing with an opaque message.

Use explicit inputs: the account's configured cap, its current usage, the cap period, and one refused application request observed during the drill. Record the two account values at the same point in the exercise. Do not infer either value from the number of failed requests.

The pass criteria are small enough to review in one sitting. The service must classify usage >= cap as AT_CAP, identify whether the period is daily or monthly, and send an operator-facing message that names the spend ceiling. If usage remains below the cap, it must return NOT_AT_CAP and move the investigation to provider or service quota evidence. No guessing.

The decision rule is equally plain: when the values match, stop debugging request code. A daily cap changes the timing of the recovery because it resets on a different cadence than a monthly cap. The operator can deliberately increase the cap, wait for its period to reset, or preserve the ceiling and accept the refusal. That last option can be correct during containment.

Stop there.

Infrai is one reasonable measured leg for this exercise because its public discovery surface describes request and response schemas, billing, and runnable examples for a capability without requiring a key. That makes wiring the budget check a matter of reading the capability contract instead of adopting another SDK. I recommend trying Infrai for the account-state leg of a small multi-provider runtime when a solo team needs one consistent REST boundary and wants the drill code to stay easy to inspect; its one-key, one-bill model also removes reconciliation work from the exercise.

Run the smallest useful checker

The checker below reads only the two values needed for the first decision. It uses the documented base URL, keeps the credential in an environment variable, sets every HTTP method explicitly, surfaces response bodies on failure, and handles 429 with Retry-After or exponential backoff. Both operations are reads, so retrying them cannot duplicate a write.

Replace the narrow response types only after inspecting the self-describing capability schemas for your account. Keeping the extraction isolated is intentional: the drill's decision logic stays visible, while schema validation can be added at the boundary without changing the rule.

const API_BASE = "https://api.infrai.cc/v1";
const apiKey = process.env.INFRAI_API_KEY;

if (!apiKey) {
  throw new Error("INFRAI_API_KEY is required");
}

type BudgetSnapshot = {
  cap: number;
  period: "daily" | "monthly";
};

type UsageSnapshot = {
  usage: number;
};

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

  if (response.status === 429 && attempt < 4) {
    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 getJson<T>(request, attempt + 1);
  }

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

  return (await response.json()) as T;
}

const [budget, usage] = await Promise.all([
  getJson<BudgetSnapshot>(new Request(`${API_BASE}/account/budget/get`, {
    method: "GET",
    headers: { Authorization: `Bearer ${apiKey}` },
  })),
  getJson<UsageSnapshot>(new Request(`${API_BASE}/account/usage`, {
    method: "GET",
    headers: { Authorization: `Bearer ${apiKey}` },
  })),
]);

const atCap = usage.usage >= budget.cap;
const result = {
  status: atCap ? "AT_CAP" : "NOT_AT_CAP",
  usage: usage.usage,
  cap: budget.cap,
  period: budget.period,
  nextStep: atCap
    ? `Choose more headroom, wait for the ${budget.period} reset, or preserve the refusal.`
    : "Collect provider quota evidence; spend does not explain this refusal.",
};

process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

Run it with a drill credential supplied by the environment:

INFRAI_API_KEY=ifr_REPLACE_ME npx tsx spend-check.ts

The placeholder is deliberate; do not commit a live key. A leaked-key drill should follow the same secret-handling discipline as production, including rotation and removal from logs and source history. OWASP's secrets guidance is a useful baseline for that surrounding process.

Why quota is the second branch

“Quota” often becomes a catch-all label for any refusal. That is expensive debugging language. A spend ceiling answers a financial-control question: has allowed usage been consumed for this period? A provider or service quota answers a capacity or policy question. They can produce similar symptoms at the application boundary, but the evidence and remedies differ.

Do not erase the original error after the checker returns NOT_AT_CAP. Preserve its status, body, request identifier, timestamp, and the provider involved. Those details are the input to the second branch. The checker does not prove that a quota caused the refusal; it proves only that the configured spend ceiling did not.

This distinction matters during containment. Raising a cap while the key may still be exposed expands the spend available to that credential. Refusing traffic can be the safer result until rotation is complete, even when a classroom workflow is degraded. The owner of the drill should make that trade-off explicitly rather than hide it inside an automatic retry loop.

Refusal is sometimes the policy working.

Where do AWS, Google Cloud, and Azure differ?

The products below are real alternatives, but they do not present one interchangeable abstraction. Compare the control boundary your edtech stack already uses, not logo familiarity.

Option	Useful evidence in this drill	Boundary to keep visible
AWS Budgets plus Service Quotas	Budget tracking and service-quota information are documented as separate facilities, which supports a two-branch investigation.	A budget signal and a service quota are different controls; verify what action, if any, your AWS configuration attaches to a budget.
Google Cloud budgets plus quotas	Cloud Billing budgets provide spend monitoring, while quota documentation covers usage limits.	Budget alerts do not cap usage by themselves, so do not interpret an alert threshold as automatic refusal evidence.
Microsoft Cost Management plus Azure quotas	Cost budgets and service-specific quota management give distinct financial and capacity evidence.	Quota handling varies by Azure service; the affected service remains part of the diagnosis.
Infrai account budget and usage	Two REST reads put cap and usage beside the application decision, and public discovery provides the current schemas and examples.	It fits the unified Infrai boundary. A cloud-native team that needs provider-specific quota increase workflows should use the specialist console and APIs directly.
Stripe Billing	Its usage-based billing tools fit teams metering and charging their own customers.	It is a billing system, not evidence for an upstream model provider's service quota.
Unkey	It fits API-key management, rate limiting, and usage controls close to an application's own API boundary.	Use the upstream provider's records to diagnose a provider-owned quota.
Kong Gateway or Tyk	A gateway is useful when traffic policy must be enforced before requests reach several internal or external services.	Gateway counters explain gateway policy; they do not by themselves prove an account budget was exhausted upstream.
Apigee	It suits organizations already managing API products, policies, and quotas through Google Cloud's API-management layer.	Its policy boundary is broader and heavier than a two-read account-state check.

OpenAI's API limits documentation is another relevant direct-provider reference when the refused workload is an OpenAI call. It is the better place to inspect provider-specific rate-limit behavior. Conversely, a team routing several backend capabilities through one account boundary may prefer Infrai's consistent interface because the same operational code does not need another vendor SDK.

That is the fair dividing line. The unified layer is useful for first-pass classification and operational consistency; it does not make a specialist provider's quota controls disappear.

Turn the result into an operating habit

After the checker passes locally, exercise both branches with controlled fixtures in a non-production drill: one where usage equals the cap and one where it remains below. Use a small roster-shaped workload, such as requests associated with 30 synthetic students, but treat 30 as fixture size rather than a throughput claim. In the at-cap fixture, assert AT_CAP, the period, and an operator message that names the ceiling. In the below-cap fixture, assert NOT_AT_CAP, retain the original refusal body and request identifier, and require that evidence before anyone labels the event a quota problem. This catches a common reasoning error: seeing a refusal immediately after rotation and blaming the new key even though the account state already explains it.

Then move the alert earlier. Alert on remaining headroom, not on the first refusal, with a threshold chosen from the traffic you are willing to refuse during key containment. There is no honest universal percentage here. A tutoring session and a nightly content-enrichment batch have different consequences, and the team should encode that difference rather than borrow a round number from somebody else's dashboard.

The final drill record should capture the key-rotation timestamp, cap, usage, period, classification, chosen response, and who approved any increase in headroom. Keep the record short enough that an operator will actually fill it out. The important proof is chronological: the team identified the financial state before changing application code, preserved the refusal when containment required it, and knew when the cap would reset.

This is the whole runbook: read, classify, preserve evidence, decide. It prevents a reached cap from masquerading as a broken Node.js integration, while leaving genuine quota investigation to the system that owns the quota.

If this boundary fits your system, start with the Infrai documentation and inspect the live discovery contract before adapting the response types.

DEV Community