Subscription Expired

Reference · Errors

subscription_expired402

Billing · Affects all endpoints

The account's paid plan has expired. Renew to restore endpoint access and call limits.

What this means

The account was on a paid plan, but the subscription has lapsed — either because the renewal payment failed, the user cancelled and the cycle ended, or the grace period after a failed payment ran out. We've moved the account back to the Sandbox tier (500 calls/month). Sandbox still includes every product endpoint — only the call volume and burst limits drop. The user can renew at any time to restore paid quota.

When you'll see this

• A user's card on file expired and the renewal charge failed.
• The user cancelled their plan and the current billing cycle has ended.
• A renewal attempt failed and the 7-day grace period expired without resolution.
• An admin manually downgraded the account to Sandbox.

Learn more about how this works

When a subscription lapses, we don't instantly cut access — there's a grace period (typically 7 days from the failed renewal) during which the user keeps paid-tier quota while we retry the charge. If the charge eventually succeeds, nothing changes from the user's perspective. If it doesn't, the account drops to Sandbox at the end of the grace period (same endpoints, 500 calls/month) and subsequent requests may surface this error when the expired paid subscription blocks continued paid access.

In practice: the message tells the user exactly what to do — renew at the dashboard. Don't add layers of indirection or try to handle this server-side; let the user see and act on it.

Example response

{
  "success": false,
  "error": "subscription_expired",
  "message": "Your subscription has expired. Please renew at asterwise.com/dashboard to continue.",
  "details": [],
  "retry_after": null,
  "doc_url": "https://docs.asterwise.com/reference/errors/subscription_expired",
  "request_id": "req_01HXYZABCDEFGH",
  "timestamp": "2026-05-25T12:34:56Z"
}

NEW TO APIS?

Quick fix

1. Sign in at asterwise.com/dashboard.
2. Check the billing section — if a payment method is expired or failed, update it.
3. Click "Renew" or "Subscribe" to restore the plan. Access returns immediately on successful payment.

PRODUCTION ENGINEER

Recovery pattern

This is a hard authorization-style boundary — the user needs to take billing action. Surface clearly, don't retry, route to the dashboard.

Python:

Production handler

Python

import httpx

class SubscriptionExpiredError(Exception):
    """The account's paid plan has lapsed. User must renew."""

def call_asterwise(url, headers, payload):
    response = httpx.post(url, headers=headers, json=payload, timeout=30)
    if response.status_code == 402:
        body = response.json()
        if body.get("error") == "subscription_expired":
            raise SubscriptionExpiredError(
                "Asterwise subscription expired. "
                "Renew at asterwise.com/dashboard to restore access."
            )
    response.raise_for_status()
    return response.json()

TypeScript

class SubscriptionExpiredError 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 === 402) {
    const body = await response.json();
    if (body.error === "subscription_expired") {
      throw new SubscriptionExpiredError(
        "Asterwise subscription expired. " +
        "Renew at asterwise.com/dashboard to restore access.",
      );
    }
  }
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

Avoid this error by

• Keep payment methods current. Card expirations are the leading cause of unexpected lapses.
• Watch for renewal-failure notification emails. We send them at the failure event and again during the grace period — both are actionable warnings before the wall.
• For team-managed accounts, make sure billing notifications go to someone who can actually update the card, not a shared inbox nobody monitors.
• If you're building on top of Asterwise for your own customers, listen for subscription_expired and surface a clear renewal CTA in your own UI rather than hiding the error.

RELATED ERRORS

insufficient_tier

reserved / unused for endpoint access (all plans share all endpoints); subscription expiry is about billing status and quota, not locked endpoint families.

already_on_plan

the renewal attempt found the user already subscribed; that's a different code path.

monthly_usage_limit_exceeded

plan is active but call budget is exhausted; not the same as expiry.