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

> ## Agent Instructions
> The OpenAPI document at /api-reference/openapi.yaml defines the target contract. Its x-reflections-availability field and each operation's availability notice identify supported test and live forms. Do not infer implementation from a schema or code sample. Live keys support account details, reads of the licenses the calling account holds as licensee or issued as talent (GET /v1/licenses?role=issuer), and GET /v1/generations?license=… for the state of outputs under such a license (summaries only: no prompt, reference, bytes or metadata). Live image checks, submissions and receipts are built but not activated: until activation, a live POST /v1/checks or /v1/generations returns 403 live_not_activated, which must not be retried. Discovery and JWKS are at the origin root (https://app.reflections.ai/.well-known/...), not under /v1.
> Three rules hold everywhere: a decision is never an error (deny and escalate are 200 responses, and a live check still evaluating is a 202 with status checking); generate nothing for a named talent without an allow; deliver nothing until the generation is allow.
> The sandbox accepts personal rk_test_ keys. Persist a separate Idempotency-Key and body for each logical /v1 POST; retry an unknown outcome with the same key and body. OAuth and Talent API MCP remain planned.

# Rate limits

> The limits per account, the headers that report them, what a 429 means, and how to raise a limit.

Sandbox rate limits use token buckets keyed by account and policy **per server process**.
Multiple instances each grant an allowance; these numbers are not a fleet-wide quota. Live-mode
limits and sessions are not available. Do not build against a promised live rate.

## Current sandbox limits

| Calls | Allowance per process |
| - | - |
| Checks (`POST /v1/checks`) | 20 per second |
| Generations (`POST /v1/generations`) | 5 per second |
| Other authenticated operations | 5 per second |
| Public receipt reads | 10 per minute per IP address |

Short bursts are absorbed until the bucket is empty. Test verification requires a key.

## Headers

Every response carries the IETF `RateLimit-Policy` and `RateLimit` header fields for the limit the
call counted against:

```http theme={null}
HTTP/1.1 200 OK
Request-Id: req_8f2k4m6p8r0t2v4x6z8b0d2f4h
RateLimit-Policy: "checks";q=20;w=1
RateLimit: "checks";r=18;t=1
```

| Field | Parameter | Meaning |
| - | - | - |
| `RateLimit-Policy` | `q` | The quota: requests allowed per window. |
| `RateLimit-Policy` | `w` | The window, in seconds. |
| `RateLimit` | `r` | Requests remaining in the current window. |
| `RateLimit` | `t` | Seconds until the quota resets. |

The supported policy names are `checks`, `generations` and `default`.

## When you exceed a limit

The call fails with `429 rate_limited` and a `Retry-After` header in seconds. Nothing ran: no
check was decided and no object was created.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 1
```

```json theme={null}
{
  "type": "https://docs.reflections.ai/errors/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}
```

Wait `Retry-After` seconds, then retry with the same `Idempotency-Key`. The retry function in
[Idempotency](/api-reference/idempotency#retry-with-the-same-key) does both. Sessions are planned and cannot be used yet.

<Warning>
  A `429` on a check is not permission. Do not generate a named talent until a retry returns
  `allow`.
</Warning>

## Stay under the limits

* Read `RateLimit` and slow down before `r` reaches zero.
* Retry unknown outcomes with the same persisted `Idempotency-Key` and body.
* Poll an escalated check or asynchronous generation no faster than once every five seconds.
* Webhooks, the name index and usage batching remain planned; they are not current alternatives to polling.

Service status is at [status.reflections.ai](https://status.reflections.ai). Rate-limit increases
and production capacity require an explicit service agreement; they are not self-service features.

## Related

<Columns cols={2}>
  <Card title="Errors" icon="ban" href="/api-reference/errors">
    Every error code and what to do.
  </Card>

  <Card title="Caching and outages" icon="bolt" href="/build/caching-and-outages">
    Reuse windows, the revocation feed and retries.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.