API v1 · 4xx

usage_limit_exceeded

HTTP status: 402 Payment Required

The workspace has spent its weekly AI budget for the current usage week. This is the primary AI limit — the one most callers will meet — and it is shared with the dashboard's AI features, as opposed to the API-only daily valve (spend_cap_exceeded). It applies to every AI-cost verb: post generation (POST /v1/posts/generations), image and carousel generation, and the knowledge/source ingests that summarise or transcribe (file POST /v1/sources, POST /v1/knowledge) — and their MCP twins.

json

{
  "error": {
    "code": "usage_limit_exceeded",
    "message": "Weekly AI usage limit reached (104% of the project budget). Resets 2026-08-17T00:00:00.000Z. Retrying before then cannot succeed; check remaining budget any time with GET /v1/usage (MCP: get_usage).",
    "request_id": "req_01J9Z…",
    "docs_url": "https://scripe.io/developers/api/v1/errors#usage_limit_exceeded",
    "details": {
      "reason": "weekly_limit",
      "scope": "ai_project",
      "percentUsed": 104,
      "resetsAt": "2026-08-17T00:00:00.000Z"
    }
  }
}

Why it refused

details.reason says whether waiting can help:

`reason`	Meaning
`weekly_limit`	A real weekly allowance, spent. It comes back at `details.resetsAt`.
`no_plan`	The workspace is on the Free plan, which includes no AI. Nothing resets; AI starts with a paid plan or the free trial, started by a workspace admin in Scripe under Settings → Billing.
`no_allowance`	This scope has no AI allowance on the workspace's plan. Nothing resets.

Only weekly_limit makes percentUsed and resetsAt meaningful: a zero allowance reads 100 from the first call. The message says the same thing in words, so an agent that relays it tells the user the right next step.

Two budgets, and which one you hit

details.scope says which meter refused you:

`scope`	What it meters
`ai_project`	One project's own weekly budget. Every personal-brand project has one.
`ai_workspace_pool`	The workspace pool — company-page projects and any AI work not tied to a project spend from it.

Those two literals are the only values it takes. The budgets reset weekly, at details.resetsAt (Monday 00:00 UTC).

How to handle it

Don't retry before resetsAt. Nothing about the workspace changes in between; the same call fails identically. For no_plan and no_allowance, a reset changes nothing either.
Pre-flight instead. GET /v1/usage (MCP: get_usage) reports the current percentage, the reset time, and canGenerate — a single boolean that is false exactly when the next AI job would be refused. Checking it costs nothing and is the supported way to schedule a batch of generations.
Surface it to your user. The percentage and the reset time are what a person needs in order to decide between waiting and upgrading; a bare "generation failed" is not actionable.

spend_cap_exceeded — the daily API-only spend cap, a separate, narrower valve. A call can be refused by either.
Usage and limits — the read that answers both before they fire.
Jobs § AI budget — how the budget meters async work.

Why it refused

Two budgets, and which one you hit

How to handle it

Related