Skip to content
Choppity API

Rate limits

The /v1 API enforces a fixed-window rate limit per root team:

60 requests per minute per root team, regardless of authentication method or whether requests come from one machine or many.

Child teams share their root team’s quota. Calls authenticated via API key or via a Firebase JWT count toward the same bucket.

Response headers

Section titled “Response headers”

Every successful or rate-limited response includes:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1745800140
  • Limit — total requests allowed in the current window
  • Remaining — requests left before you’ll get a 429
  • Reset — unix-seconds timestamp when the window rolls over

When you exceed the limit

Section titled “When you exceed the limit”

Subsequent requests within the same one-minute window return 429:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1745800140


{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded: 60 requests/minute"
  }
}

Wait until X-RateLimit-Reset and retry. We don’t ship a Retry-After header yet — read Reset instead.

Avoiding the limit

Section titled “Avoiding the limit”

The flows most callers run aren’t anywhere near 60 rpm:

  • Per clip job: 1 POST, then poll GET /v1/clips/:id every ~10s for ~2 minutes — about 12 requests total.
  • Per render: 1 POST, then poll GET /v1/renders/:id every ~5s for ~30s — about 6 requests.

If you find yourself hitting the limit, the fix is usually to register a webhook and stop polling. A single webhook delivery replaces an entire polling loop.