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

# Rate Limiting

> Understanding rate limits, tiers, and how to handle 429 responses

# Rate Limiting

The Glider Platform API uses a two-layer rate limiting system to protect service
availability while allowing legitimate traffic.

## Two-Layer System

### Layer 1: Global Per-IP Limit

Every request from a single IP address counts toward a global circuit breaker,
regardless of which endpoint is called. This prevents any single client from
overwhelming the service.

### Layer 2: Per-Tier Per-IP Limits

Routes are grouped into tiers based on cost and sensitivity. All routes in the
same tier share one counter per IP, preventing bypass by varying path parameters.

| Tier              | Description                               |
| ----------------- | ----------------------------------------- |
| Tier 1 (critical) | Expensive operations (e.g. LLM inference) |
| Tier 2 (general)  | Standard public endpoints                 |
| Tier 3 (burst)    | Read-heavy or cached endpoints            |

A request must pass **both** layers to succeed. If either the global or tier
limit is exceeded, the request is rejected with a `429` status.

## Response Headers

Every response from a rate-limited route includes standard rate limit headers:

| Header                  | Description                                               |
| ----------------------- | --------------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window            |
| `X-RateLimit-Remaining` | Requests remaining before the limit is reached            |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the window resets           |
| `Retry-After`           | Seconds to wait before retrying (only on `429` responses) |

When both layers apply, the headers reflect the **tighter** (per-tier) limit so
clients can pace themselves accurately.

## 429 Response Format

When a rate limit is exceeded, the API returns:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 42 seconds.",
  "retryAfter": 42,
  "correlationId": "corr_abc123",
  "requestId": "req_xyz789"
}
```

| Field           | Description                                    |
| --------------- | ---------------------------------------------- |
| `error`         | Always `"Too Many Requests"`                   |
| `message`       | Human-readable description including wait time |
| `retryAfter`    | Seconds until the current window resets        |
| `correlationId` | Correlation ID for tracing across systems      |
| `requestId`     | Unique request identifier                      |

Include the `correlationId` and `requestId` when contacting Glider support about
rate limiting issues.

## Local and Staging Dev Auth

Wallet-backed `dev-auth` sessions use a relaxed wallet-session bucket in local
and staging runtimes so browser replay and profiling runs do not immediately hit
standard end-user tRPC ceilings.

* This applies only to local and staging dev-auth traffic.
* Production does not accept `dev-auth` tokens or synthetic auth headers.
* Normal API-key, cookie, SIWE, and Privy production limits are unchanged.

## Retry Strategy

1. Read the `Retry-After` header (or `retryAfter` field) from the 429 response.
2. Wait at least that many seconds before retrying.
3. Use exponential back-off with jitter if you receive repeated 429s.
4. Avoid retry storms — stagger retries across clients when possible.