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

# Rate Limits

> Information about API rate limits and how to handle them

The OneBalance API implements rate limiting to ensure fair usage and availability of the service for all users. Rate limits are applied on a per-API key basis.

## Current Rate Limits

| User Type           | Request Rate Limit     | Concurrent Connections |
| ------------------- | ---------------------- | ---------------------- |
| Public API Key      | 60 requests per minute | 1 per IP address       |
| Authenticated Users | Custom rate limits     | Custom limits          |

<Note>
  Authenticated users receive higher rate limits based on their specific needs. Please contact our
  team if you require increased limits for your production application.
</Note>

Once you exceed your limit, your requests will be temporarily rejected until the rate limit window resets.

## Rate Limit Headers

The rate limiting information is included in the response headers of each request:

| Header                  | Description                                                                  |
| ----------------------- | ---------------------------------------------------------------------------- |
| `x-ratelimit-limit`     | The maximum number of requests you're permitted to make per minute           |
| `x-ratelimit-remaining` | The number of requests remaining in the current rate limit window            |
| `x-ratelimit-reset`     | The time at which the current rate limit window resets in Unix epoch seconds |

As long as the `x-ratelimit-remaining` count is above zero, you'll be able to make additional requests.

## How Rate Limiting Works

Each request contributes toward your rate limit count for one complete minute. This means that the entire rate limit doesn't reset at once. Rather, each request expires individually one minute after it was made.

The value of the `x-ratelimit-reset` header indicates when the oldest request will expire and no longer count toward your limit.

## Handling Rate Limits

If you exceed the rate limit, the API will return a `429 Too Many Requests` status code. We recommend implementing the following strategies to handle rate limits effectively:

1. **Monitor the rate limit headers** in your API responses to track your usage
2. **Implement exponential backoff** when receiving 429 responses
3. **Pace your requests** to avoid hitting the limits, especially for batch operations
4. **Cache responses** when possible to reduce the number of API calls

## Sample Rate Limit Headers

```bash Terminal theme={null}
x-ratelimit-limit: 60
x-ratelimit-remaining: 58
x-ratelimit-reset: 60
```

## Sample Rate Limit Exceeded Response

```json Rate Limit Exceeded theme={null}
{
  "error": "TooManyRequests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "statusCode": 429,
  "timestamp": "2024-12-18T14:38:24.793Z",
  "path": "/api/assets/list"
}
```

## Best Practices

* Space out requests that would otherwise be issued in bursts
* Implement retry logic with exponential backoff when receiving 429 responses
* For high-volume operations, consider batching requests where appropriate
* Use the public API key for testing and development only, as it has lower rate limits

<Note>
  Some endpoints may have special rate limit requirements that are independent of the general limits
  defined above.
</Note>