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:

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.

Rate-limit response headers

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

When you exceed a limit

The API responds with HTTP 429 Too Many Requests:

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

{
  "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.
• 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.