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

> ## Agent Instructions
> Flowy is a node-based AI creative platform: you generate images, video, audio, 3D and vector on an infinite Canvas, refine on the Studio timeline, and export or publish from the same project.
> Prefer the Flowy MCP server (https://mcp.tryflowy.ai/mcp) or the REST API at https://apis.tryflowy.ai/v1 for programmatic work. Install with `flowy mcp install` from the @flowy/cli package.
> Credits are workspace-scoped. Generations reserve credits on start and only deduct on success, so failed runs refund automatically.

# Rate limits

> Per-key request limits, the rate-limit headers, and how to back off.

Every API key is rate limited per minute. The limit is applied per key, so one key's traffic never eats into another's.

## Limits

| Credential                         | Default limit         | Per-credential override |
| ---------------------------------- | --------------------- | ----------------------- |
| Secret key (`flowy_…`)             | 60 requests / minute  | Yes                     |
| Publishable key (`flowy_pk_…`)     | 120 requests / minute | Yes                     |
| OAuth access token (`flowy_oat_…`) | 60 requests / minute  | No                      |

Secret and publishable keys are two **separate** classes with their own default: a publishable key gets the higher 120/minute default because it's meant to be called directly from a browser, where many users share the same key. Both defaults can be overridden per key (under advanced options when you create or edit it). An [OAuth access token](/api/oauth), minted for a connected app or the [MCP](/api/mcp), always uses the secret-key default and has no per-token override.

Separately, each key may have at most a small number of **concurrent runs** in flight at once.

## Rate-limit headers

Successful responses include headers describing your current window, and a `429` adds `Retry-After`:

| Header                  | Meaning                                                      |
| ----------------------- | ------------------------------------------------------------ |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window (per minute). |
| `X-RateLimit-Remaining` | Requests remaining in the current window.                    |
| `X-RateLimit-Reset`     | Unix epoch second at which the window resets.                |
| `Retry-After`           | Seconds to wait before retrying: sent on a `429`.            |

```http theme={"theme":{"light":"github-light","dark":"vesper"}}
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1893456000
```

## When you're rate limited

Exceeding the per‑minute limit (or the concurrent‑run limit) returns `429 Too Many Requests`:

```json theme={"theme":{"light":"github-light","dark":"vesper"}}
{ "error": "rate limit exceeded" }
```

The response carries a `Retry-After` header (in seconds) and `X-RateLimit-Remaining: 0`.

<Tip>
  Read `X-RateLimit-Remaining` proactively and slow down as it approaches `0`. On a `429`, wait the `Retry-After` interval before retrying, and apply exponential backoff with jitter if you keep getting limited. Keep your in‑flight runs below the key's concurrency limit.
</Tip>

## Spend caps are separate

A rate limit caps **how often** you call; a [daily spend cap](/api/authentication#protecting-your-keys) caps **how many credits** a key burns per day. Hitting the spend cap returns `402`, not `429`. See [Errors](/api/errors) for the full status‑code table.