Skip to main content

​
spend_cap_exceeded

HTTP status: 402 Payment Required The workspace has hit its daily AI spend cap for the current UTC day. The cap is plan-dependent and resets at 00:00 UTC. This is the API-only abuse valve; the primary AI budget is the weekly usage_limit_exceeded limit.

​
Why we shipped a hard cap

Every AI-cost endpoint (post generation, KB ingest with summarisation, source ingest from file) calls into a third-party provider whose pricing the customer doesn’t see directly. A runaway loop on the customer side could rack up several hundred dollars before they notice. The hard cap puts a clear ceiling on how much pain a misbehaving integration can cause in a single day, scoped per workspace so it doesn’t penalise co-tenants.

​
Per-plan caps

Only plans that can reach the API at all appear here — every other tier is rejected with 403 plan_not_eligible before it can spend anything. TRIAL is the sharp edge: it is admin-assigned rather than purchased, it clears the plan gate as a BUSINESS equivalent, but its cap is matched on the raw label — so it spends against $1/day, twenty times tighter than the lowest paid tier. Values may change; the error’s details payload is authoritative. The cap is per UTC day; the bucket resets to 0¢ at 00:00 UTC.

​
How to handle it

  1. Don’t retry blindly. A retry will hit the same cap. Either wait for the bucket to reset or pre-flight-check with GET /v1/usage (MCP: get_usage), which reports today’s apiSpend.remainingCents and a canGenerate boolean.
  2. Surface the details to your end users so they understand they need to wait — or upgrade — before more AI work can be queued.
  3. Pre-allocate manually. If you know you need to push 200 posts through tomorrow, work backwards from the cap and plan the cadence.
  4. Need more headroom? Upgrade to BUSINESS (10,000¢/day) or talk to us about an ENTERPRISE plan with no cap.

​
What we count

Each AI-cost job pre-reserves an estimate against the bucket at submit time, then reconciles to the provider-reported actual cost on the worker side. Negative deltas (we overestimated) are credited back to the bucket within a few seconds of the job finishing. Failed jobs that never reached a provider also get their estimate refunded. You’ll never get billed for the same cents twice.
  • usage_limit_exceeded — the weekly AI budget, the primary limit. This daily cap is the narrower valve on top of it.
  • Usage and limits — the read that answers both before they fire.
  • Jobs — long-running operations.
  • Conventions — error envelope shape.