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

# Usage Limits

> Per-organization limits on request rate, export rate, and concurrent design tasks.

Moda enforces three kinds of limits on API traffic:

* **Request rate** — how many HTTP calls per minute each API key can make.
* **Export rate** — a separate, lower cap on export calls (`POST /v1/canvases/{id}/export`) per minute.
* **Concurrent design tasks** — how many agent-driven design tasks (`POST /v1/tasks`, `POST /v1/remix` with a prompt) your organization can have running at once.

All three return `429 Too Many Requests`. The concurrent-task cap scales with your plan; the request-rate and export-rate caps are currently flat defaults. Some limits can be raised for your organization on request — see [Need a higher limit?](#need-a-higher-limit).

## Request rate

Every API response carries a `Retry-After` header when rate-limited. If you exceed your minute budget, you receive:

```json theme={null}
{
  "error": {
    "type": "rate_limited",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "retry_after_ms": 30000
  }
}
```

with HTTP status `429 Too Many Requests`. Back off and retry after the hint.

### Default request-rate limits

| Plan        | Requests per minute |
| ----------- | ------------------- |
| `free`      | 120                 |
| `free_beta` | 120                 |
| `paid`      | 120                 |
| `ultra`     | 120                 |

Today the rate limit is a flat 120 rpm for all plans, applied per API key. We plan to move to per-plan and per-org limits in a future release; when we do, we'll pre-announce via our changelog and the `Moda-Version` header.

## Export rate

Exporting a canvas (`POST /v1/canvases/{id}/export`) is metered separately from — and more tightly than — the general request rate, since each export spins up a headless render. Polling an export's status (`GET /v1/canvases/{id}/export-status`) does **not** count against this cap.

Exceeding the export rate returns the same `429 rate_limited` envelope shown above, carrying `Retry-After: 60` and a message that names the export cap. Back off and retry after the hint.

### Default export-rate limits

| Plan        | Exports per minute |
| ----------- | ------------------ |
| `free`      | 25                 |
| `free_beta` | 25                 |
| `paid`      | 25                 |
| `ultra`     | 25                 |

The default is a flat 25 exports per minute on every plan. Unlike the general request rate, the export cap is **configurable per organization** — if a batch-export workload legitimately needs more, support can raise your org's export limit without a plan change (see [Need a higher limit?](#need-a-higher-limit)).

## Concurrent design tasks

Every organization has a cap on how many design tasks can be **queued or running** at the same time. The cap applies across:

* `POST /v1/tasks` (REST API) — counts against your org's task cap.
* `POST /v1/remix` with a `prompt` (REST API) — counts against your org's task cap.
* Design-dispatch tools on the **Moda MCP server** (`start_design_task`, `remix_design`) — also counts against your org's task cap.
* Webhook-triggered tasks — count against your org's task cap.

The cap does **not** apply to:

* Interactive design sessions in the Moda web app (WebSocket).
* Slack integration traffic.
* Internal / background jobs we run on your behalf.

When your org is at its cap, new requests return `429 Too Many Requests` with `Retry-After: 30`:

```json theme={null}
{
  "error": {
    "type": "rate_limited",
    "code": "concurrency_limit_exceeded",
    "message": "Rate limit exceeded: 10/10 concurrent tasks active. Please wait for existing tasks to complete before submitting new ones."
  }
}
```

Polling your existing tasks via `GET /v1/tasks/{id}` is unaffected by the cap — only *starting* new tasks counts toward it.

### Default concurrent-task limits

| Plan        | Max concurrent tasks |
| ----------- | -------------------- |
| `free`      | 3                    |
| `free_beta` | 3                    |
| `paid`      | 10                   |
| `ultra`     | 15                   |

These defaults are tuned for the typical integration. If you consistently hit your cap and your workflow legitimately requires more parallelism, **[contact support](mailto:support@moda.app)** — we can raise your org's limit without a plan change.

## Recommended client behavior

* **Use the `Retry-After` header.** It's populated on both rate-limit and concurrency-limit responses.
* **Back off with jitter**, not a tight loop. A simple `time.sleep(retry_after + random())` is enough.
* **Pipeline, don't parallel-spray.** If you have a batch of 50 designs to generate, submit them in waves of N (where N = your cap) and wait for each wave to finish before the next. See [task polling](/api-reference/tasks/get-task-status).
* **Share one API key across your integration**, not one per deployment. Concurrency is per-org, not per-key, so using multiple keys does not raise your effective cap.
* **Branch on `error.type`, not on HTTP status.** The request-rate limit, the export-rate cap, and the concurrency cap all return 429; the `type` field (`rate_limited`) is the same for all three, but future error codes may differentiate them via `error.code` (`rate_limit_exceeded` vs `concurrency_limit_exceeded`).

## Need a higher limit?

Email **[support@moda.app](mailto:support@moda.app)** with:

* Your organization name or slug.
* Which limit you're hitting (request rate, export rate, or concurrent tasks).
* The peak concurrency or rpm your integration needs.
* A sentence on the use case.

We grant case-by-case per-org overrides for legitimate workloads — you don't need to move plan tiers to get a temporary or permanent bump.