Insufficient Tier
insufficient_tier402
This endpoint requires a higher plan than the one your account is currently on.
What this means
Your API key is valid and your account is in good standing — but the endpoint you tried to call is gated behind a paid tier that your plan doesn't include. The request was rejected before any calculation ran. We return 402 (Payment Required) rather than 403 to signal that this is a billing-side decision, not a permission one. Upgrading the plan immediately unlocks the endpoint.
When you'll see this
- A key on the Sandbox (free) plan tried to call an endpoint that requires Builder or higher.
- A Builder-plan key tried to call a Launch-only endpoint like advanced compatibility or AI synthesis.
- The account's previous plan included this endpoint, but after a downgrade or expiry the endpoint moved out of scope.
- Internal testing on a sandbox key hit a tier wall that production keys won't hit.
Learn more about how this works
Asterwise has four plans: Sandbox (free), Builder, Launch, and Scale. Higher plans unlock more endpoint families, higher monthly call limits, and more burst capacity. This error is the boundary marker for the endpoint-tier dimension specifically — the call-limit dimension surfaces as monthly_usage_limit_exceeded instead.
In practice: this is the cleanest possible upgrade signal. The endpoint exists, your code works, your auth works — the only blocker is the plan. Most teams hit this once during development when they try a feature that's on a higher tier, and again when they migrate from prototyping to production.
Example response
{
"success": false,
"error": "insufficient_tier",
"message": "This endpoint requires a higher tier. Please upgrade your plan.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/insufficient_tier",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- Sign in at asterwise.com/dashboard and check which plan your account is on.
- Review the pricing page for which endpoints each tier includes.
- Upgrade to the tier that includes this endpoint. The new tier takes effect immediately for new requests.
This error is not retriable and should be surfaced clearly — silently swallowing it leads to mysterious feature gaps in your product.
Python:
Production handler
- Python
- TypeScript
import httpx
class AsterwiseTierError(Exception):
"""Account plan doesn't include this endpoint."""
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") == "insufficient_tier":
raise AsterwiseTierError(
f"Endpoint requires a higher plan. "
f"Upgrade at asterwise.com/dashboard. "
f"request_id={body.get('request_id')}"
)
response.raise_for_status()
return response.json()
class AsterwiseTierError 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 === "insufficient_tier") {
throw new AsterwiseTierError(
`Endpoint requires a higher plan. ` +
`Upgrade at asterwise.com/dashboard. ` +
`request_id=${body.request_id}`
);
}
}
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json();
}
Avoid this error by
- Test against your production tier early in development, not just on Sandbox. Tier walls discovered at launch time are launch delays.
- If you're building features that span multiple tiers (some users on free, some on paid), feature-flag the higher-tier endpoints on your side rather than letting them 402.
- For B2B integrations where your customers bring their own Asterwise account, check their tier on first connection and surface "this feature requires X plan" before they hit it mid-flow.
- Subscribe to plan-change webhooks if you maintain Asterwise integrations across many customers — silent downgrades are the leading cause of this error in production.