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

# Rate Limiting & Gateway Quotas

> Learn about Hexagraph's dual-tiered rate limits, daily query quotas, response headers, and GET /rate-limit monitoring endpoint.

Hexagraph Core enforces a dual-tiered rate limiter to protect capacity, prevent scraping, and ensure fair resource allocation for all users across REST and GraphQL interfaces.

***

## Rate Limit Tiers & Quotas

Rate limits are tracked per IP address across short-burst minute windows and 24-hour daily quotas:

| Tier                             | Scope                                     | Limit                          | Description                                     |
| :------------------------------- | :---------------------------------------- | :----------------------------- | :---------------------------------------------- |
| **Short-Burst IP Limit**         | All REST & GraphQL Routes                 | **30 requests / min**          | Prevents aggressive burst traffic and scraping. |
| **IP Daily Quota - List/Filter** | List and filter endpoints across entities | **500 requests / day**         | Allocates fair-share query quota per IP.        |
| **IP Daily Quota - Search**      | `/autocomplete` routes                    | **50 requests / day**          | Allocates search query quota per IP.            |
| **System Daily Pool Cap**        | Total gateway capacity                    | **10,000 List / 1,000 Search** | System-wide capacity pool cap.                  |

***

## Response Headers

Every API response from Hexagraph Core includes real-time rate limit headers:

```http theme={null}
HTTP/1.1 200 OK
X-RateLimit-IP-Limit: 30
X-RateLimit-IP-Remaining: 28
X-RateLimit-IP-Reset-Seconds: 42
X-RateLimit-Daily-Limit: 500
X-RateLimit-Daily-Remaining: 455
```

* `X-RateLimit-IP-Limit`: Short-burst 1-minute limit.
* `X-RateLimit-IP-Remaining`: Remaining requests in current 1-minute window.
* `X-RateLimit-IP-Reset-Seconds`: Seconds until the 1-minute window resets.
* `X-RateLimit-Daily-Limit`: Total daily list/filter query quota.
* `X-RateLimit-Daily-Remaining`: Remaining daily list/filter queries.

***

## Checking Rate Limit Status (`GET /rate-limit`)

Send a `GET` request to `/rate-limit` at any time to inspect your current IP status and daily balances:

```bash cURL theme={null}
curl -X GET "https://api.hexagraph.in/rate-limit"
```

**Example Response**:

```json theme={null}
{
  "ip": "203.0.113.195",
  "minute_rate_limit": {
    "limit": 30,
    "remaining": 28,
    "reset_seconds": 42
  },
  "daily_quota": {
    "list_filter": {
      "limit": 500,
      "remaining": 455,
      "reset_seconds": 43200
    },
    "search": {
      "limit": 50,
      "remaining": 46,
      "reset_seconds": 43200
    }
  }
}
```

***

## Rate Limit Exceeded Responses (`HTTP 429`)

When a rate limit is exceeded, Hexagraph returns an HTTP `429 Too Many Requests` response containing human-readable time strings and exact UTC reset timestamps:

### Minute Burst Limit Exceeded

```json theme={null}
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "IP rate limit exceeded (max 30 requests per minute). Please try again in 42 seconds (at 11:40:32 UTC).",
  "reset_in_seconds": 42,
  "reset_at_utc": "2026-08-05T11:40:32.000Z"
}
```

### Daily Quota Exceeded

```json theme={null}
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Your daily quota for List/Filter requests has been exceeded. Please try again in 3 hours, 14 minutes, and 22 seconds (at 00:00:00 UTC).",
  "reset_in_seconds": 11662,
  "reset_at_utc": "2026-08-06T00:00:00.000Z"
}
```

***

## Best Practices

* **Inspect Response Headers**: Check `X-RateLimit-IP-Remaining` and `X-RateLimit-Daily-Remaining` on API calls.
* **Use GraphQL for Multi-Entity Operations**: Retrieve outputs, authors, and sources in a single GraphQL query (`/graphql`) to preserve quota.
* **Implement Exponential Backoff**: On receiving HTTP 429, wait for the duration specified in `reset_in_seconds` or `X-RateLimit-IP-Reset-Seconds`.