Rate Limits & Quotas — Markdown source

> **AI Agents**: Index `/api/llms.txt` | Full EN `/api/llms-full-en.txt` | Full ZH `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# Rate Limits & Quotas

SupaNexus may apply multiple independent limit layers. Exact thresholds depend on your deployment — check with your platform administrator or the Developer Console.

## 1. IP rate limit

Applies to **all routes** (including requests without a valid API key), scoped by client IP.

Typical default: about **120 requests per minute** per IP (when enabled).

When exceeded:

- **HTTP 429**
- OpenRouter format (same on `/v1/*` and other routes):

```json
{
  "error": {
    "code": 429,
    "message": "You are being rate limited."
  }
}
```

The response may include a **`Retry-After`** header (seconds).

> **Note:** This limit is per **IP address**, not per API key.

## 2. Usage quota (optional)

May apply to `POST /v1/chat/completions` only when configured for your organization or project.

When exceeded:

- **HTTP 429**
- `error.code`: **429** (numeric)
- **`Retry-After`** header may be set (seconds)

## 3. Account balance (optional)

May apply to `POST /v1/chat/completions` only when prepaid credits or balance checks are enabled.

| HTTP | Meaning |
|------|---------|
| 402 | Not enough credits for this period (`error.code=402`) |
| 403 | Organization context missing |

**402 vs 429:** Insufficient balance uses **402 Payment Required**. Quota or spend-cap limits use **429 Too Many Requests**.

## Comparison table

| Layer | Typical scope | Error format | HTTP |
|-------|---------------|--------------|------|
| IP rate limit | All routes | OpenRouter `{error:{code,message}}` | 429 |
| Usage quota | Chat only | OpenRouter | 429 |
| Account balance | Chat only | OpenRouter | 402 |

## Best practices

- Implement exponential backoff on 429 and respect `Retry-After`.
- Use separate API keys per application to simplify usage tracking in the console.
- Monitor usage in the Developer Console before hitting limits.

## Related

- [Errors](./errors.md)
- [Chat Completions](./chat-completions.md)