# Rate Limiting

### Overview

To ensure fair use and maintain the stability of our API, we implement rate limiting on all endpoints. Rate limiting restricts the number of API requests a user can make within a specific time frame. This helps prevent abuse, ensures equitable resource distribution, and maintains optimal performance.

### Rate Limiting Rules

* **Rate Limit**: Each user is allowed to make up to **100 read requests** or **25 write requests** per minute.
* **Time Window**: The rate limit is calculated over a rolling 1-minute window.

### Rate Limit Headers

Rate limit status is communicated via HTTP headers in API responses. These headers provide information on the current usage and the limits applied.

#### **Headers**

* **X-RateLimit-Limit**: The maximum number of requests allowed in the current time window.
* **X-RateLimit-Remaining**: The number of requests remaining in the current time window.
* **X-RateLimit-Reset**: The time at which the current rate limit window resets, represented as a Unix timestamp.

#### **Example Response Headers**

```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 75
X-RateLimit-Reset: 1629478800
```

#### Exceeding Rate Limits

When the rate limit is exceeded, the API will return a `429 Too Many Requests` status code. The response will include the `Retry-After` header, indicating the time (in seconds) after which the user can retry the request.

#### **Example Error Response**

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit. Please wait before making more requests."
}
```

### Monitoring Rate Limits

To avoid exceeding the rate limit, monitor the `X-RateLimit-Remaining` header in the API responses. Adjust the frequency of your requests based on the remaining allowance and the reset time provided.

#### Usage Example

**Normal Request**

```http
GET /v1/investments
```

**Response Headers**

```http
HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1629478800

{
  "data": "..."
}
```

**Exceeded Rate Limit**

```http
GET /v1/investments
```

**Response**

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit. Please wait before making more requests."
}
```

### Best Practices

1. **Monitor Usage**: Regularly check the rate limit headers to ensure you stay within the allowed limits.
2. **Handle 429 Responses Gracefully**: Implement retry logic to handle `429 Too Many Requests` responses, using the `Retry-After` header to determine when to retry.
3. **Optimize Requests**: Combine multiple data needs into a single request where possible to reduce the total number of requests.
4. **Use Caching**: Cache responses locally to reduce the need for repetitive API calls.