Rate limits

The Hoursmith API enforces per-token rate limits with burst and sustained buckets. Read the limits and the headers that report them.

The API is rate-limited per token, with separate plans getting more headroom. Limits use two buckets: a short burst window and a longer sustained window.

The limits

Plan	Burst	Sustained
Studio	30 requests / 10 seconds	600 requests / 60 seconds
Agency	60 requests / 10 seconds	1,200 requests / 60 seconds

Unauthenticated requests (e.g. a wrong or missing token) are limited to 10 requests / 60 seconds per IP to deter token-guessing.

Rate-limit headers

Every response includes headers describing your current budget:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 583
X-RateLimit-Reset: 1717603260

X-RateLimit-Limit — your sustained budget.
X-RateLimit-Remaining — requests left in the current window.
X-RateLimit-Reset — Unix timestamp (seconds) when the window resets.

When you're limited

If you exceed a bucket, the API returns 429 with a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 7

{ "error": { "code": "rate_limited", "message": "Too many requests." } }

Handling limits gracefully

Respect `Retry-After`

On a 429, wait the number of seconds in Retry-After before retrying — don't hammer.

Back off exponentially

For repeated 429s, add exponential backoff with jitter so many clients don't retry in lockstep.

Watch `X-RateLimit-Remaining`

Slow down proactively as Remaining approaches zero rather than waiting for a 429.

Batch where you can: use list endpoints with filters and pagination instead of many single-record reads.

Was this page helpful?