Rate limits¶
Each API key has its own budget of requests per minute. Going over it answers 429 rate_limited, with a Retry-After header that says how many seconds to wait.
The limits¶
| Requests | Limit | Counted per |
|---|---|---|
Reads: GET |
300 a minute | API key |
| Writes: every other method | 60 a minute | API key |
| Orders: new servers, upgrades and extra bandwidth | 10 a minute | API key |
| Requests without a key | 30 a minute | IP address |
| Failed key checks | 20 in 10 minutes | IP address |
- Every request counts, including those that are refused.
- Two keys have two budgets, even when they belong to the same person.
- After 20 failed key checks from an address, every key sent from it is refused for the rest of the 10 minutes, a valid one too. See Failed attempts.
{
"type": "https://docs.hosthatch.com/api/errors#rate_limited",
"title": "Rate limited",
"status": 429,
"detail": "Request was throttled. Expected available in 36 seconds.",
"code": "rate_limited",
"instance": "/api/v1/me/"
}
The limit in front of the API¶
60 requests a minute per IP address
A rule at HostHatch's network edge answers before the API's own limits. More than 60 requests a minute from one IP address to the API get an HTML 429 page, without a Retry-After header and without problem details. The address is then refused for about a minute.
It counts all requests from the address together, whatever key they carry, so two scripts behind one address share it. Plan for 60 requests a minute per IP address, and treat a 429 that isn't application/problem+json as "wait 60 seconds".
Stay under the limits¶
- Poll actions and orders every few seconds, not in a tight loop, and less often as time passes.
- Read one resource rather than its whole list when you only need one.
- Give each script or agent its own key, so one busy client doesn't spend another's budget.
- On a
429, wait forRetry-After, or 60 seconds when there is none, then go on at a slower pace. Add a little random delay, so that clients don't all retry at the same moment.