# Rate limits

How public API request limits, headers, and retries work.

Authenticated public API requests are rate limited per workspace. Requests made with any valid key for the same workspace share the same bucket, so creating more keys does not increase the limit. The public OpenAPI schema at `/api/v1/openapi.json` is not rate limited.

Current default limits:

| Window     | Limit          |
| ---------- | -------------- |
| Per minute | 60 requests    |
| Per day    | 1,000 requests |

## Response headers

Successful limited requests include headers for the currently binding window:

| Header                  | Meaning                                 |
| ----------------------- | --------------------------------------- |
| `X-RateLimit-Limit`     | The request limit for the active window |
| `X-RateLimit-Remaining` | Requests remaining in that window       |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets   |

## When you hit the limit

If either the minute or day window is exhausted, the API returns `429 TOO_MANY_REQUESTS`:

```json
{
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Rate limit exceeded"
  }
}
```

The response also includes `Retry-After`, in seconds. Wait at least that long before retrying.

## Client guidance

- Treat `Retry-After` as authoritative for `429` responses.
- Add backoff and jitter when retrying automated jobs.
- Cache stable reads, especially project configuration and metadata lists.
- Paginate list requests instead of making many narrow repeated calls.