Rate limits and the monthly allowance

Two different things, often confused.

Rate limits (an abuse brake)

Going over any of them gives 429 with code rate_limited. Only the per-minute request limit sends a Retry-After header, so do not make your retry logic depend on one being there: on a deploy or authentication 429 there is nothing to read, and retrying immediately just burns the next window.

The monthly allowance (billing)

• 5,000 requests included per billing account per UTC calendar month
• $1.00 per 100,000 requests after that, taken from account credit
• Pooled per account, not per key. Per-key counts exist for attribution only
• Resets on the 1st, UTC

Going over does not block anything. Requests keep working and the overage is posted to account credit in batches rather than as one ledger line per request.

Reading your usage

Every counted response carries headers:

X-Api-Quota-Limit: 5000
X-Api-Quota-Remaining: 4943
X-Api-Quota-Used: 57

GET /api/v1/account returns the same figures in the body, along with the period dates, overage_rate ($1.00) and overage_unit_requests (100,000). The Developer tab shows the month's usage, a per-key split, and the previous twelve months.

What does not count

These are refused before metering, so they do not spend the allowance:

• 401 bad or missing key
• 429 rate limited
• 402 API locked because hourly billing is not unlocked
• 403 suspended or closed account
• 403 read-only key attempting a write
• OPTIONS preflight

Everything else counts, including a 404 for a server id you do not own and a 400 for a malformed body.

Staying under it

5,000 requests a month is small if you poll. A monitoring check every minute is about 43,200 requests in a 30-day month. After the 5,000 included requests, that is about 38,200 billable requests, or roughly $0.38. Two habits help:

• Poll a list, not each server. GET /api/v1/servers returns every server in one request, with the same fields the detail endpoint gives. This month's transfer per server is on GET /api/v1/account under bandwidth.servers, so you do not need a request per box to see who is using the pool.
• Poll fast only while something is happening. Every ten seconds during a deploy is fine. Every ten seconds forever is a bill.