Headers
Every response from an API-key-authenticated request includes the rate-limit state, so you can self-throttle without waiting to hit a 429.
The headers fire on every status code —
200, 400, 404, 429, 502, etc. — as long as the request authenticated via API key. Anonymous (web-form) and Google-session-token requests do not receive these headers because they’re not subject to the same per-key quota.
Handling 429
When you exceed the limit, the API returns:Retry-After header. Wait that many seconds before your next request. Don’t poll faster — repeated 429s won’t shorten the wait, they just waste sockets.
Self-throttling
WatchX-RateLimit-Remaining on normal traffic and slow down before you hit the wall. A small headroom (e.g. pause when remaining drops below 10) absorbs the slop from in-flight requests that haven’t decremented yet. For higher concurrency, issue a separate key per worker — each key has its own independent 120/min bucket.