Rate limits

Per-team token-bucket limits on V1 endpoints.

Default tiers

Each team gets the following bursting capacity. The bucket refills at the sustained rate.

Endpoint class	Capacity (burst)	Refill (sustained)
POST /v1/images, POST /v1/videos	120	60 / minute
GET (lists, single fetches, balance, team, usage)	1200	600 / minute
POST /v1/files (coming in v1.1)	60	30 / minute
POST /v1/webhook_endpoints (coming in v1.1)	10	10 / minute

Headers on every response

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1714752900

• X-RateLimit-Limit is the bucket capacity for this endpoint class.
• X-RateLimit-Remaining is the tokens left after this request.
• X-RateLimit-Reset is the epoch second at which the bucket would be back to full, assuming no further requests.

When you hit the limit

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714752912
Content-Type: application/json

{
  "error": {
    "type": "rate_limit",
    "code": "too_many_requests",
    "message": "Rate limit exceeded for images_post. Retry after 12s.",
    "request_id": "req_01HXMQ7Z3K8Y2ABCDEFGHJKM",
    "doc_url": "https://docs.aurous-labs.com/errors/too_many_requests"
  }
}

Sleep Retry-After seconds and retry. Don’t hammer — the bucket only refills at the sustained rate.

Implementation notes

• Limits are per-team, keyed off the API key’s team_id. Multiple keys on the same team share the bucket.
• Buckets are computed atomically in Redis with a Lua script — no race window between read and write.
• Each endpoint class has its own bucket, so heavy POST traffic doesn’t starve your reads.
• POST /v1/images/:id/cancel is bucketed under images_post regardless of whether the canceled generation is img_* or vid_* (single shared bucket on the cancel route — a pure-video team’s cancel storm would still draw from images_post). Runaway cancels can’t drain the GET read bucket.

Need a higher tier?

Email [e-mail] with your team ID and expected workload. Manual bumps are available before the override UI ships.