> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.scripe.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage limit exceeded

# `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`](./spend_cap_exceeded.md)).
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 theme={null}
{
  "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://docs.scripe.io/api/v1/errors#usage_limit_exceeded",
    "details": {
      "scope": "ai_project",
      "percentUsed": 104,
      "resetsAt": "2026-08-17T00:00:00.000Z"
    }
  }
}
```

## 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

1. **Don't retry before `resetsAt`.** Nothing about the workspace
   changes in between; the same call fails identically.
2. **Pre-flight instead.** [`GET /v1/usage`](../usage.md) (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.
3. **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.

## Related

* [`spend_cap_exceeded`](./spend_cap_exceeded.md) — the *daily*
  API-only spend cap, a separate, narrower valve. A call can be
  refused by either.
* [Usage and limits](../usage.md) — the read that answers both before
  they fire.
* [Jobs § AI budget](../jobs.md#ai-budget) — how the budget meters
  async work.