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

# Rate limiting

> Understand Hyperline API rate limits, response headers, and best practices to handle 429 responses with retries and exponential backoff strategies.

The Hyperline API implements rate limiting to ensure fair usage and protect the platform from abuse. This page details the rate limiting policies and how to handle them effectively.

## Rate limits

### Core API

| Operation type | Limit | Window |
| - | - | - |
| Read (GET) | 200 | 10 seconds |
| Write (POST, PUT, PATCH, DELETE) | 50 | 10 seconds |

### Events ingestion API

The events ingestion API has separate rate limits:

| Operation type | Limit | Window |
| - | - | - |
| All requests | 1,000 | 10 seconds |

Additionally, the following payload size limits apply:

* **`POST /v1/events/batch`**: maximum of 5,000 events per request
* **`DELETE /v1/events`**: maximum of 5,000 event IDs per request

## Rate limit headers

API responses include the following rate limit headers:

* `X-RateLimit-Limit`: The maximum number of requests allowed in the current window
* `X-RateLimit-Remaining`: The number of requests remaining in the current window
* `X-RateLimit-Reset`: The date and time when the rate limit window resets
* `Retry-After`: The minimum number of seconds to wait before retrying (only when the limit has been reached)

## Handling rate limits

When you exceed the rate limit, the API returns a **429 Too Many Requests** HTTP status code. The response body is:

```json theme={null}
Too many requests
```

### Best practices

1. **Monitor rate limits**: Track the `X-RateLimit-Remaining` header to anticipate when you're approaching the limit
2. **Implement backoff**: When you receive a 429 response:
   * Wait until the date specified in the `X-RateLimit-Reset` header
   * Consider implementing exponential backoff for retries
3. **Batch requests**: When possible, combine multiple operations into a single request
4. **Cache responses**: When appropriate, cache responses to reduce the number of API calls

## Example response headers

Rate limit not exceeded:

```text theme={null}
HTTP/1.1 200 OK
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 150
X-RateLimit-Reset: 2025-04-15T10:18:08.107Z
```

Rate limit exceeded:

```text theme={null}
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2025-04-15T10:18:08.107Z
Retry-After: 5
```

## Custom rate limits

If your application requires higher rate limits, contact the Hyperline team via the in-app chat. The team works with you to establish appropriate limits based on your use case.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.