Billing limits

When a request returns quota_exceeded or a feature is silently unavailable, the cause is one of three things: monthly search-unit quota, wallet overage budget, or plan-tier feature gate. Each has a different remedy.

Symptom

See Plans and limits for the per-plan numbers.

Check 1: where you stand on the monthly quota

Open Settings → Billing → Usage. Three things are surfaced:

You can also pull this programmatically with an admin key:

curl -X GET https://app.aacsearch.com/api/v1/projects/<projectId>/usage \
  -H "Authorization: Bearer aa_admin_..."

The response includes searchUnitsUsed, searchUnitsCap, walletBalanceMinor (in kopecks), periodStartUtc, periodEndUtc.

Check 2: overage budget

If you are on a paid plan, you can enable wallet-funded overage. Once enabled, requests above the soft cap are billed against the wallet (priced per 1k search-units) instead of returning 429.

Enable overage in Settings → Billing → Overage budget. Set a maximum monthly spend ceiling so you do not get surprised.

Check 3: feature gate

Some features are not part of every plan tier:

A request to a gated feature returns:

{
	"error": "feature_not_available_on_plan",
	"message": "Curations require the Pro plan or higher.",
	"requiredPlan": "pro",
	"upgradeUrl": "https://app.aacsearch.com/settings/billing"
}

Upgrade in Settings → Billing → Change plan.

Check 4: plan-tier ceilings

Each plan caps the number of indexes:

Trying to create one more returns:

{
	"error": "plan_limit_reached",
	"message": "Free plan allows 1 index. Upgrade to Starter for up to 3.",
	"requiredPlan": "starter"
}

Soft vs hard cap (detail)

Soft cap fires:
  ├─ Email + dashboard alert to billing contact
  ├─ Requests still served if overage budget enabled
  └─ Wallet starts deducting if overage on

Hard cap fires:
  ├─ All search and ingest endpoints return 429 quota_exceeded
  ├─ Connectors stop accepting sync calls
  └─ Resets at 00:00 UTC on 1st of next month

The two coincide when overage is disabled. With overage enabled, hard cap fires only when the wallet itself runs dry.

Per-key vs per-org

These are distinct:

Hitting rateLimitPerMinute returns 429 rate_limit_exceeded (different error code) and is unrelated to billing. See Rate limits.

Fix matrix

Predicting next month

To estimate whether you will fit in the current plan:

const usage = await admin.getUsage(7); // last 7 days
const dailyAvg = usage.rows.reduce((s, r) => s + r.searchUnits, 0) / 7;
const projected30d = dailyAvg * 30;
console.log("projected this month:", projected30d);
console.log("plan cap:", planCap);

If projected30d is approaching the plan cap, upgrade preemptively rather than waiting for the alert.

Diagnostics packet

Related

• Plans and limits — per-plan quota numbers
• Rate limits — per-key (not per-org) rate enforcement
• Errors and rate limits — error code matrix
• Auth errors — for 401/403 (not 429)