RATE_LIMITED

Monthly request quota exceeded — your plan is hard-capped (typically Free).

What this means

RATE_LIMITED fires when your monthly request quota is exhausted AND your plan is hard-capped (no credit overflow allowed). This is almost always the Free tier — paid tiers fall through to credit billing instead and only see RATE_LIMITED if their credit balance is also zero (which surfaces as PAYMENT_REQUIRED). The response includes a `reset_at` field with the ISO timestamp of the next billing cycle.

When you'll see it

HTTP 429. Body always includes code: "RATE_LIMITED". Branch on code, never on the human-readable message — wording can change without notice; the code is the stable contract.

Example response

{
  "status": "error",
  "code": "RATE_LIMITED",
  "message": "Monthly quota exceeded",
  "reset_at": "2026-06-01T00:00:00.000Z"
}

How to handle

Wait until the reset, upgrade your plan, or buy credits (paid tiers only — Free can't purchase). For automated systems, capture `reset_at` from the response and pause until that timestamp. For consumer-facing applications, surface a clear "daily limit reached" message and steer the user to upgrade. Don't loop-retry — you'll just get the same 429 immediately.

Suggested handling in a Node client:

if (data.code === 'RATE_LIMITED') {
  // Out of monthly quota. Don't retry — wait or escalate.
  const resetMs = new Date(data.reset_at).getTime() - Date.now();
  notifyOps(`Onto quota reset in ${Math.round(resetMs / 1000 / 60 / 60)}h`);
  throw new Error(data.message);
}

Related errors

See the full error index for the complete catalog with the handling switch statement covering every code at once.