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

# Rate Limits

> Understanding VecTrade API rate limits, quotas, and optimization strategies.

# Rate Limits

## Overview

VecTrade uses a **token bucket** rate limiting algorithm per API key. Limits vary by plan tier and endpoint category.

## Plan Limits

| Plan         | Requests/min | Monthly API calls | Burst  | Concurrent |
| ------------ | ------------ | ----------------- | ------ | ---------- |
| Free         | 30           | 10,000            | 5      | 2          |
| Standard     | 120          | 100,000           | 20     | 5          |
| Professional | 300          | 500,000           | 50     | 20         |
| Enterprise   | Custom       | Custom            | Custom | Custom     |

## Rate Limit Headers

Every response includes rate limit information:

| Header                     | Description                        | Example      |
| -------------------------- | ---------------------------------- | ------------ |
| `X-VQ-RateLimit-Limit`     | Max requests per window            | `1000`       |
| `X-VQ-RateLimit-Remaining` | Requests remaining in window       | `987`        |
| `X-VQ-RateLimit-Reset`     | Window reset time (Unix timestamp) | `1715800060` |
| `Retry-After`              | Seconds to wait (only on 429)      | `2`          |

## Handling Rate Limits

### SDK Auto-Retry

Both official SDKs automatically handle rate limiting with exponential backoff:

```python theme={null}
# Python — retries are automatic
client = VecTrade(max_retries=3)  # Default: 2

try:
    quote = client.quotes.get("AAPL")
except RateLimitError as e:
    # Only raised after all retries exhausted
    print(f"Rate limited. Wait {e.retry_after}s")
```

```typescript theme={null}
// TypeScript — retries are automatic
const client = new VecTrade({ maxRetries: 3 });

try {
  const quote = await client.quotes.get('AAPL');
} catch (e) {
  if (e instanceof RateLimitError) {
    console.log(`Wait ${e.retryAfter}s`);
  }
}
```

### Manual Rate Limit Monitoring

```python theme={null}
# Access rate limit info from response metadata
quote = client.quotes.get("AAPL")
print(f"Remaining: {client.last_response.rate_limit.remaining}")
print(f"Resets at: {client.last_response.rate_limit.reset_timestamp}")
```

## Optimization Strategies

### 1. Use Batch Endpoints

Instead of individual requests per symbol, use batch endpoints:

```python theme={null}
# ❌ 5 requests (5 rate limit tokens)
for symbol in ["AAPL", "GOOGL", "MSFT", "AMZN", "NVDA"]:
    client.quotes.get(symbol)

# ✅ 1 request (1 rate limit token)
quotes = client.quotes.batch(["AAPL", "GOOGL", "MSFT", "AMZN", "NVDA"])
```

### 2. Use Webhooks for Real-Time Updates

Instead of polling for changes, subscribe to webhooks:

```python theme={null}
# ❌ Polling every 5 seconds (720 requests/hour)
while True:
    quote = client.quotes.get("AAPL")
    time.sleep(5)

# ✅ Webhook (0 requests — server pushes to you)
client.webhooks.create(
    url="https://your-app.com/webhooks",
    events=["quote.update"],
    symbols=["AAPL"],
)
```

### 3. Cache Responses Client-Side

```python theme={null}
from functools import lru_cache

@lru_cache(maxsize=100, ttl=60)  # Cache 60 seconds
def get_fundamentals(symbol: str):
    return client.fundamentals.get(symbol)
```

### 4. Use Field Filtering

Request only the fields you need to reduce payload size:

```python theme={null}
quote = client.quotes.get("AAPL", fields=["price", "volume"])
```

## Quota Exceeded vs Rate Limited

| Scenario                 | HTTP Status | Error Type         | SDK Exception        | Retryable  |
| ------------------------ | ----------- | ------------------ | -------------------- | ---------- |
| Too many requests/minute | 429         | `rate_limit_error` | `RateLimitError`     | Yes (auto) |
| Monthly quota exhausted  | 429         | `quota_exceeded`   | `QuotaExceededError` | No         |

<Warning>
  `QuotaExceededError` is NOT retryable — you've exhausted your monthly allocation.
  Upgrade your plan at [vectrade.io/vtrade/developer](https://vectrade.io/vtrade/developer).
</Warning>