Monthly Usage Limit Exceeded

Reference · Errors

monthly_usage_limit_exceeded429

Rate Limiting · Endpoints that take an API key

Your account has used up its monthly API call budget. Upgrade the plan or wait until the 1st of next month (UTC).

What this means

Your account has consumed all the API calls included in its current plan for this calendar month. The request was rejected before any calculation ran. Unlike burst limits (which clear in 60 seconds), this limit clears at 00:00 UTC on the 1st of next month. There's no retry_after field — the wait is days, not seconds.

When you'll see this

• Your usage grew faster than expected and you hit the monthly ceiling before the month ended.
• A bug in your code is calling Asterwise repeatedly without caching, burning through call volume.
• You're on the free Sandbox plan (500 calls/month) and hit the ceiling during testing or a small launch.
• Your traffic is normal but the plan is undersized for your current usage shape.

Learn more about how this works

Every Asterwise plan has a monthly call budget: Sandbox 500, Builder 10,000, Launch 50,000, Scale 300,000. We count every successful (2xx) request against that budget, including results served from cache; failed requests (4xx and 5xx) don't count. The budget is shared by every key on the account. The counter resets at 00:00 UTC on the 1st of each calendar month, whatever day your subscription renews; a payment or renewal doesn't reset it, and upgrading raises the limit straight away while the calls already made this month still count.

Worth knowing: this error is a billing-tier signal, not a pacing one. Retrying won't help. The only fixes are upgrading the plan, optimizing your call patterns to use fewer requests, or waiting for the month to reset.

Example response

{
  "success": false,
  "error": "monthly_usage_limit_exceeded",
  "message": "Monthly API call limit reached. Upgrade your plan to continue.",
  "details": [],
  "retry_after": null,
  "doc_url": "https://docs.asterwise.com/reference/errors/monthly_usage_limit_exceeded/",
  "request_id": "req_01HXYZABCDEFGH",
  "timestamp": "2026-05-25T12:34:56Z"
}

NEW TO APIS?

Quick fix

1. Check your current usage at asterwise.com/dashboard under the Usage section.
2. If your traffic is going to keep growing, upgrade to a plan that fits your call volume.
3. If this is unexpected, audit your code — usually one un-cached endpoint or a debug loop is responsible for most of the consumption.

PRODUCTION ENGINEER

Recovery pattern

This error is not retriable in any useful sense. Surface it as a billing-state event to your own monitoring and degrade gracefully — don't loop and don't silently fail.

Python:

Production handler

Python

import httpx
import logging

logger = logging.getLogger(__name__)

class AsterwiseBudgetExhausted(Exception):
    """Monthly call budget consumed. Upgrade plan to continue."""

def call_asterwise(url, headers, payload):
    response = httpx.post(url, headers=headers, json=payload, timeout=30)
    if response.status_code == 429:
        body = response.json()
        if body.get("error") == "monthly_usage_limit_exceeded":
            logger.critical(
                "Asterwise monthly budget exhausted",
                extra={"request_id": body.get("request_id")},
            )
            raise AsterwiseBudgetExhausted(body.get("message"))
    response.raise_for_status()
    return response.json()

TypeScript

class AsterwiseBudgetExhausted extends Error {}

async function callAsterwise(url: string, headers: HeadersInit, payload: unknown) {
  const response = await fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(payload),
  });
  if (response.status === 429) {
    const body = await response.json();
    if (body.error === "monthly_usage_limit_exceeded") {
      console.error("Asterwise monthly budget exhausted", {
        request_id: body.request_id,
      });
      throw new AsterwiseBudgetExhausted(body.message);
    }
  }
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

Avoid this error by

• Cache results aggressively. Natal chart calculations for a given birth never change — there's no reason to recompute on every page load. One cache hit per user per session is realistic.
• Subscribe to usage-warning emails. We send notifications at 80% and 100% of plan budget so you can act before this error fires.
• Monitor your call rate against your plan's monthly ceiling. If you're trending above 80% by mid-month, plan an upgrade rather than waiting for the wall.
• Don't poll. If your product needs current data (transit positions, etc.) for many users, compute once and broadcast, don't call once per user per refresh.