Rate limits
Requests are limited to 5 per second, counted per token. The limit is generous for typical use — batch or back off if you need to pull large amounts of data.
Rate-limit headers
Every response includes headers describing your current budget:
| Header | Description |
|---|---|
X-RateLimit-Limit |
The maximum number of requests allowed in the window. |
X-RateLimit-Remaining |
Requests remaining in the current window. |
When you exceed the limit, the API responds with 429 Too Many Requests and adds:
| Header | Description |
|---|---|
Retry-After |
Seconds to wait before retrying. |
X-RateLimit-Reset |
Unix timestamp when the window resets. |
{
"message": "Too Many Attempts."
}
Handling 429s
Read Retry-After and pause before retrying. A small exponential backoff with jitter is the
safest pattern for bursty workloads. If you consistently hit the limit, spread requests out or
cache responses — meta.tzdb_version tells you when the underlying data actually changed, so
cached results stay valid until the next tzdb release.