> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# Rate limits

FastPix limits how many API requests each workspace and organization can make, per endpoint, so a sudden burst of traffic is slowed down rather than degrading the platform for everyone. The limits are generous enough for normal use.

## How limits are applied

Each request is counted against two limits at the same time:

| Level            | Counted across                                         |
| ---------------- | ------------------------------------------------------ |
| **Workspace**    | All requests made with credentials for one workspace   |
| **Organization** | All requests from every workspace in your organization |

A request goes through only when both limits have capacity left. The organization limit puts a ceiling on the combined traffic of all your workspaces. Because the organization's sustained rate is also 1 request/second per endpoint, that rate is shared across all your workspaces.

Limits are tracked per endpoint, where an endpoint is an HTTP method plus a path. Each endpoint has its own allowance, so a burst of `GET /v1/on-demand` calls does not use up your allowance for `POST /v1/on-demand`. Calls to the same endpoint with different IDs share one allowance: `GET /v1/on-demand/{mediaId}` counts as one endpoint whatever the `mediaId` is.

### Burst and sustained rate

Each limit works like a bucket of tokens:

* **Burst:** the maximum number of requests you can send in quick succession. It is the size of the bucket, so a read burst of 100 lets you make up to 100 `GET` requests back to back.
* **Sustained rate:** how quickly the bucket refills, which is the request rate you can keep up over time. At 1 request per second, one token returns every second.

Every request uses one token. When the bucket is empty, FastPix rejects requests until it refills.

## Default limits

These limits apply to every API endpoint.

| Request type                             | Level        | Burst | Sustained rate   |
| ---------------------------------------- | ------------ | ----: | ---------------- |
| Read (`GET`)                             | Workspace    |   100 | 1 request/second |
| Read (`GET`)                             | Organization |   250 | 1 request/second |
| Write (`POST`, `PUT`, `PATCH`, `DELETE`) | Workspace    |    20 | 1 request/second |
| Write (`POST`, `PUT`, `PATCH`, `DELETE`) | Organization |    50 | 1 request/second |

## Rate-limit response headers

Successful responses include these headers. They describe whichever limit is closest to running out for that request:

| Header                  | Description                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `X-RateLimit-Limit`     | The burst size of that limit                                 |
| `X-RateLimit-Remaining` | Requests left before the limit is reached                    |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the limit will be back to full |

## When you exceed a limit

The API responds with HTTP 429 Too Many Requests:

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 3
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1760438400
```

```json
{
  "success": false,
  "error": {
    "code": 429,
    "message": "rate_limited",
    "description": "You have exceeded the allowed request rate. Please retry after 3 seconds."
  }
}
```

`Retry-After` gives the number of seconds to wait before the request will succeed.

## Best practices

* **Respect `Retry-After`.** On a 429, wait at least the number of seconds given in the `Retry-After` header before you retry.
* **Back off exponentially.** If retries keep failing, increase the wait each time and add a little random jitter. This stops many clients from retrying at the same moment.
* **Watch `X-RateLimit-Remaining`.** Slow down before you reach zero instead of waiting for a 429.
* **Spread out bulk jobs.** For large batches, such as uploads or metadata updates, send requests at a steady pace instead of all at once.
* **Use webhooks instead of polling.** Listen for status-change events rather than calling `GET` in a loop. See [Set up webhooks](/webhooks/set-up-webhooks).
* **Cache responses that rarely change,** such as configurations and signing keys.

## Need higher limits?

The default limits suit most integrations. If your use case needs higher limits, [contact us](https://www.fastpix.com/contact-us).

#### Frequently asked questions

By default, each endpoint allows a burst of 100 read (`GET`) requests and 20 write (`POST`, `PUT`, `PATCH`, `DELETE`) requests per workspace, with an organization-wide ceiling of 250 reads and 50 writes. Each bucket refills at a sustained 1 request per second. Limits are counted per endpoint, so one endpoint running hot does not affect the others.

Read the `Retry-After` header and wait at least the number of seconds it gives before retrying, then back off exponentially with jitter if retries keep failing. Watch `X-RateLimit-Remaining` to slow down before you hit zero, and move polling loops to webhooks. The FastPix SDKs retry 429 for you automatically.

Each request counts against both a workspace limit and an organization limit, and goes through only when both have capacity. The organization limit caps the combined traffic of every workspace, so one busy workspace can use up shared organization capacity.

No. Rate limits apply to REST API requests only. Delivery of your videos to viewers is served over the CDN and is not rate limited.