API Rate Limiting

To keep the API fast and reliable for everyone, the Hivelocity API limits how many
requests a single client can make within a rolling time window. Limits are applied
per client IP address, and they reset on a fixed one-hour window that begins
with your first request. All requests counted toward your limit — across every
endpoint you call — share the same window, so the counter for your IP resets one hour
after that first request rather than per individual endpoint.

How much you're allowed depends on whether your request is authenticated. Anonymous
(unauthenticated) traffic is held to a lower ceiling, while requests made with a valid
API token are granted a much higher allowance.

If you operate from behind a shared NAT or proxy, be aware that
the limit is keyed off the source IP we see, so multiple clients sharing one egress IP
will draw from the same pool.

Default limits

A small number of trusted integration partners are configured with custom limits; if
your integration needs a higher allowance, contact Hivelocity support to discuss
options.

Monitoring your usage

Every API response includes rate-limit headers so you can track your remaining budget
and back off gracefully before you hit the ceiling:

When you exceed the limit

If you go over your allowance, the API responds with HTTP 429 Too Many Requests
and a JSON body describing the error:

{
  "code": 429,
  "description": "Your IP is rate limited."
}

When you receive a 429, stop sending requests and wait until the window resets. Use
the X-RateLimit-Reset header to determine how long to wait, and design your client to
respect these headers and apply exponential backoff rather than retrying immediately.