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.

{
  "error": {
    "code": "spend_cap_exceeded",
    "message": "Daily AI spend cap reached (1998¢ of 2000¢). Resets at 00:00 UTC.",
    "request_id": "req_01J9Z…",
    "docs_url": "https://docs.scripe.io/api/v1/errors#spend_cap_exceeded",
    "details": {
      "bucketDate": "2026-05-26",
      "capCents": 2000,
      "spentCents": 1998,
      "estimateCents": 5
    }
  }
}

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

Every plan can reach the API, so every plan has a cap. Knowledge ingest (add_to_knowledge_base) is not judged against the weekly AI budget, as in the dashboard, so this daily cap is its only limit.

TRIAL is the sharp edge: it is admin-assigned rather than purchased, it is treated as a BUSINESS equivalent for plan-gated features, but its cap is matched on the raw label — so it spends against $1/day, the same as FREE.

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.

Related

• 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.