Monthly Usage Limit Exceeded
monthly_usage_limit_exceeded429
Your account has used up its monthly API call budget. Upgrade the plan or wait until the next billing cycle.
What this means
Your account has consumed all the API calls included in its current plan for this billing month. The request was rejected before any calculation ran. Unlike burst limits (which clear in 60 seconds), this limit clears at the start of your next billing cycle. 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 cycle reset.
- 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 higher. We count every successful request against that budget — failed requests (4xx errors caused by your input, for example) don't count. The counter resets on the first day of each billing cycle, not on the calendar month boundary.
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 cycle 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"
}
- Check your current usage at asterwise.com/dashboard under the Usage section.
- If your traffic is going to keep growing, upgrade to a plan that fits your call volume.
- If this is unexpected, audit your code — usually one un-cached endpoint or a debug loop is responsible for most of the consumption.
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
- TypeScript
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()
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-cycle, 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.