# Rate Limits & Plans

CuteMarkets uses a tiered subscription model. Options and stocks are separate subscription products, but both use the same plan ladder, throughput rules, freshness rules, lookback windows, and quote gating.

## Plans

| Plan | Yearly billing | Monthly billing | Requests / min | Requests / day | Data delay | Historical lookback | Quotes endpoint |
|------|----------------|-----------------|---------------|----------------|------------|---------------------|-----------------|
| **Free** | €0 | €0 | 10 | 5,000 | 15 min delayed | 3 years | — |
| **Developer** | €49 / mo | €59 / mo | Unlimited | Unlimited | 15 min delayed | 7 years | — |
| **Expert** | €99 / mo | €119 / mo | Unlimited | Unlimited | Live | 10 years | ✓ |
| **Commercial** | €399 / mo | €469 / mo | Unlimited | Unlimited | Live | 10 years | ✓ |

## Products

Options and stocks are purchased independently. Keep using `tier` for the Options API subscription and `stock_tier` for the Stocks API subscription in profile responses.

- A Developer options plan does not unlock stock access unless you also subscribe to Developer or higher for stocks.
- A stock Expert plan unlocks stock quotes, not options quotes.
- API keys are product-scoped. Use an Options API key for options endpoints and a Stocks API key for stock endpoints.

## Historical lookback

Each plan enforces a hard limit on how far back in time you can query. Requests that include a date or timestamp parameter that falls outside your plan's window are rejected with a `403 lookback_exceeded` error.

| Plan | Lookback | Affected parameters |
|------|----------|---------------------|
| **Free** | 3 years | `from_date`, `date`, `as_of`, `expiration_date.*`, `timestamp.*` |
| **Developer** | 7 years | Same as above |
| **Expert** | 10 years | Same as above |
| **Commercial** | 10 years | Same as above |

The cutoff is calculated relative to the time of the request (rolling window, not a fixed calendar year).

### Example 403 Response

```bash
curl \
  "https://api.cutemarkets.com/v1/options/contracts/?underlying_ticker=SPY&as_of=2020-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "status": "ERROR",
  "request_id": "cm_9c4a1d82e3f04b6a8d2e7f1c5b0a9e3d",
  "error": {
    "code": "lookback_exceeded",
    "message": "Your Free plan allows up to 3 years of historical lookback. Upgrade your plan to access older data."
  }
}
```

## Rate limit headers

Every API response includes headers that tell you your current usage:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Plan` | Your current plan: `Free`, `Developer`, `Expert`, or `Commercial` |
| `X-RateLimit-Limit-Minute` | Per-minute request limit (`unlimited` for paid plans) |
| `X-RateLimit-Remaining-Minute` | Remaining requests this minute |
| `X-RateLimit-Limit-Day` | Daily request limit (`5000` for Free, `unlimited` for paid plans) |
| `X-RateLimit-Remaining-Day` | Remaining requests today |

## Example 429 Response

If you exceed your plan's request limit, you'll receive an `ERROR` envelope like this:

```bash
curl \
  "https://api.cutemarkets.com/v1/options/chain/NFLX/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "status": "ERROR",
  "request_id": "cm_f38efe47d6b24bf691281cb973a60b61",
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Upgrade your plan for higher limits."
  }
}
```