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

# Rate Limiting

> Understand rate limits, quotas, and best practices for efficient API usage.

The Hey Chocolate API enforces rate limits to ensure fair usage and platform stability.

## Rate limit headers

Every API response includes rate limit information:

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per window              |
| `X-RateLimit-Remaining` | Remaining requests in the current window |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets    |

## Limits by tier

| Tier           | Requests/min | Calculations/day | Asset renders/day |
| -------------- | ------------ | ---------------- | ----------------- |
| **Free**       | 60           | 1,000            | 100               |
| **Growth**     | 600          | 50,000           | 5,000             |
| **Enterprise** | 6,000+       | Unlimited        | 50,000+           |

## Handling rate limits

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "errors": [
    {
      "message": "Rate limit exceeded. Retry after 12 seconds.",
      "extensions": {
        "code": "RATE_LIMIT_EXCEEDED",
        "retryAfter": 12
      }
    }
  ]
}
```

**Best practices:**

* Implement exponential backoff when receiving `429` responses
* Cache frequently accessed data (product scores change infrequently)
* Use pagination to reduce the number of requests
* Batch related queries into a single GraphQL request

## Caching recommendations

Product detail page (PDP) data is ideal for edge caching since impact scores update infrequently:

| Data type                | Recommended TTL        |
| ------------------------ | ---------------------- |
| Product impact scores    | 1 hour                 |
| Equivalency translations | 1 hour                 |
| Supply chain data        | 15 minutes             |
| Calculation results      | Do not cache (dynamic) |
| DPP documents            | 24 hours               |