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

# Rate Limits

> Understanding and managing rate limits in Winnie

Rate limits are an essential part of maintaining service quality and ensuring fair usage across all users. This guide explains how rate limits work in Winnie and how to handle them effectively.

## Understanding Rate Limits

Rate limits control how many requests you can make to Winnie's API within a specific time period. These limits are based on your subscription plan and are designed to ensure optimal performance for all users.

### Rate Limit Structure

* **Requests per second (RPS)**: Maximum number of requests you can make per second
* **Credits per month**: Total number of credits available for your plan
* **Burst capacity**: Short-term capacity to handle traffic spikes
* **Concurrent connections**: Maximum number of simultaneous connections

## Available Plans and Limits

| Plan         | Cost        | Credits     | Requests/sec | API Keys |
| ------------ | ----------- | ----------- | ------------ | -------- |
| Free         | \$0/month   | 500,000     | 10           | 1        |
| Developer    | \$49/month  | 10,000,000  | 50           | 3        |
| Business     | \$499/month | 100,000,000 | 200          | 5        |
| Professional | \$999/month | 200,000,000 | 500          | 15       |
| Enterprise   | Custom      | Custom      | Custom       | Custom   |

## Credit Usage by Method

Different API methods consume different amounts of credits:

| Category     | Credit Cost | Example Methods                         |
| ------------ | ----------- | --------------------------------------- |
| Lightweight  | 1           | `eth_blockNumber`, `net_version`        |
| Standard     | 2           | `eth_getBalance`, `eth_getCode`         |
| Heavy        | 5           | `eth_getLogs`, `debug_traceTransaction` |
| Transaction  | 10          | `eth_sendRawTransaction`                |
| Archive Data | 20          | Historical data queries                 |

## Handling Rate Limit Errors

When you exceed your rate limits, you'll receive a 429 (Too Many Requests) error:

```json theme={null}
{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "details": {
      "limit": 50,
      "reset": 1647123456,
      "retry_after": 60
    }
  }
}
```

### Recommended Handling Strategy

1. Implement exponential backoff
2. Monitor your usage
3. Consider upgrading your plan
4. Cache responses when possible

## Monitoring Usage

Track your usage through the Winnie Dashboard:

* Real-time request monitoring
* Credit consumption tracking
* Rate limit status
* Usage alerts and notifications

## Burst vs. Sustained Limits

* **Burst limits**: Short-term capacity for handling traffic spikes
* **Sustained limits**: Long-term average request rate
* **Credit system**: Flexible allocation of resources

## Optimization Techniques

<Accordion title="Batch Requests">
  Combine multiple requests into a single batch to reduce overhead.
</Accordion>

<Accordion title="Cache Responses">
  Implement caching for frequently accessed data.
</Accordion>

<Accordion title="Use WebSockets">
  WebSocket connections are more efficient for real-time data.
</Accordion>

<Accordion title="Implement Retry Logic">
  Use exponential backoff for retrying failed requests.
</Accordion>

## Auto-scaling Options

For paid plans, Winnie offers auto-scaling capabilities:

* Automatic credit top-up
* Burst capacity allocation
* Dynamic rate limit adjustment
* Usage-based scaling

## Common Issues

<Accordion title="Unexpected rate limit errors">
  Check your current usage and plan limits. Consider implementing better request throttling.
</Accordion>

<Accordion title="Credit exhaustion">
  Monitor your credit usage and implement caching strategies.
</Accordion>

<Accordion title="Burst capacity issues">
  Implement proper request queuing and backoff strategies.
</Accordion>

## Response Headers

Winnie includes helpful headers in responses:

| Header                  | Description                          |
| ----------------------- | ------------------------------------ |
| `X-RateLimit-Limit`     | Your plan's rate limit               |
| `X-RateLimit-Remaining` | Remaining requests in current window |
| `X-RateLimit-Reset`     | Time until rate limit resets         |
| `X-Credits-Remaining`   | Remaining credits for the month      |