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.

{
  "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:

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 (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 — 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.