---
title: Rate limits
description: Request limits for the free API, the headers that report them, and how to handle 429 responses.
---

# Rate limits

The API is free to read, so it is rate limited to keep it fast for everyone. Limits apply per API token, in one-minute windows.

| What | Limit |
|---|---|
| Reads (`GET`) | 300 requests per minute per token |
| Writes (everything else, including quotes and payments) | 60 requests per minute per token |
| Failed authentication | 60 per minute per IP address |
| Quotes without an account | 30 per minute per IP address |
| Paid monitors | 1,000 per workspace |

## Headers

Successful responses report the current window:

| Header | Meaning |
|---|---|
| `RateLimit-Limit` | Requests allowed in this window |
| `RateLimit-Remaining` | Requests left in this window |
| `RateLimit-Reset` | Seconds until the window resets |

When you go over, the response is `429 Too Many Requests` with `"error": "rate_limited"` and a `Retry-After` header in seconds. Wait that long, then continue.

```python
import time, requests

def get(url, key):
    while True:
        response = requests.get(url, headers={"X-API-Key": key})
        if response.status_code != 429:
            return response
        time.sleep(int(response.headers.get("Retry-After", "5")))
```

## Polling status

Monitors are checked on their own schedule (every 10 seconds at the fastest), so polling more often than a monitor's interval returns the same answer. To watch many monitors, call `GET /api/v1/monitors` once per interval instead of fetching each monitor; it returns every monitor's `current_status`. To be told about outages instead of polling, add a [notification contact](/docs/api#notification-contacts).

## Fair use

UpHeron monitors services you operate or are allowed to monitor. Using monitors to load-test, flood or probe third-party services is not allowed. Tokens or workspaces used for abuse are revoked without refund.