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

# Rate Limits

> API rate limiting and throttling policies

## Limits

Rate limits are enforced per app using a sliding window counter. Every response includes rate limit headers so you can track your usage in real time.

| Environment      | Requests per minute |
| ---------------- | ------------------- |
| All environments | 1,000               |

## Rate Limit Headers

Rate-limited API responses include these headers:

| Header                  | Description                                             |
| ----------------------- | ------------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per window                     |
| `X-RateLimit-Remaining` | Requests remaining in the current window                |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets                   |
| `Retry-After`           | Seconds until the window resets (only on 429 responses) |

## Handling Rate Limits

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

```json theme={null}
{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
  "trace_id": "d4e5f6a7-b8c9-0123-defg-234567890123"
}
```

### Recommended Approach

Use the `X-RateLimit-Reset` header to wait until the window resets before retrying. Fall back to exponential backoff with jitter if the header is missing:

```javascript theme={null}
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const resetAt = response.headers.get("X-RateLimit-Reset");
      const waitMs = resetAt
        ? parseInt(resetAt) * 1000 - Date.now()
        : Math.pow(2, attempt) * 1000 + Math.random() * 1000;

      await new Promise((resolve) => setTimeout(resolve, Math.max(waitMs, 1000)));
      continue;
    }

    return response;
  }

  throw new Error("Max retries exceeded");
}
```

## Best Practices

* **Batch requests** where possible instead of making many individual calls
* **Cache responses** for data that doesn't change frequently (providers, facilities)
* **Use pagination** with larger page sizes to reduce the number of requests
* **Monitor headers** — check `X-RateLimit-Remaining` to throttle proactively before hitting the limit