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

# 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.

**Limits may change.** We raise limits without notice — a loosening never breaks your integration — and announce any reduction in advance in the [changelog](/changelog). Always treat the `X-RateLimit-Limit` response header as the authoritative current value; don't hard-code the numbers below into retry logic.

| Endpoint class                                                                                                                                     | Capacity (burst) | Refill (sustained) |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------------------ |
| `POST /v1/images`, `POST /v1/videos`                                                                                                               | 120              | 60 / minute        |
| Character synthesis — `POST /v1/characters` (create), `POST /v1/characters/{id}/refs/regenerate`, `POST /v1/characters/{id}/resynthesize`          | 30               | 15 / minute        |
| Character writes — `POST /v1/characters/uploads/init`, `…/uploads/classify`, `PATCH`/`DELETE /v1/characters/{id}`, `POST /v1/characters/{id}/save` | 60               | 30 / minute        |
| Character reads — `GET /v1/characters`, `GET /v1/characters/{id}`                                                                                  | 240              | 120 / minute       |
| `GET` (lists, single fetches, balance, team, usage)                                                                                                | 1200             | 600 / minute       |
| `POST /v1/files`                                                                                                                                   | 60               | 30 / minute        |
| `POST /v1/webhook_endpoints`                                                                                                                       | 10               | 10 / minute        |
| `POST /v1/{images,videos}/estimate`                                                                                                                | 240              | 120 / minute       |

Character synthesis is limited below the image endpoint because each create or resynthesize fans out to four image generations internally. At 15 creates/minute that is 60 image generations/minute — matching the `POST /v1/images` budget. The three synthesis routes **share one bucket** (see the note under [Implementation notes](#implementation-notes) below).

## Headers on every response

```http theme={null}
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 theme={null}
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.

The `message` names the endpoint class you exceeded — for example `characters_synthesize` rather than the `images_post` shown above. Switch on `error.code` (always `too_many_requests`), never on the human-readable `message` string.

## Implementation notes

* Limits are per-team, keyed off the API key's `team_id`. Multiple keys on the same team share the bucket.
* Bucket counts are atomic across concurrent requests on the same team — 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.
* Character synthesis shares one per-team bucket across `POST /v1/characters`, `POST /v1/characters/{id}/refs/regenerate`, and `POST /v1/characters/{id}/resynthesize`. A burst of regenerations or resynthesizes draws down the same 30-token bucket as new creates — they are not independently budgeted. If you batch-onboard characters while also regenerating poses, budget both against the single 15/minute sustained rate. Note that `regenerate` mints a single pose but still draws one full token from this bucket (which is sized for 4-pose creates), so a regenerate-heavy workload is capped at 15/minute even though it produces fewer images. (`X-RateLimit-Remaining` reflects consumption across all three routes.)

## Need a higher tier?

Email **[support@aurous-labs.com](mailto:support@aurous-labs.com)** with your team ID and expected workload.