Throttle limits

A 429 means you are sending too fast. Back off and retry: the same request will succeed once you slow down. No v2 rate limit is published yet, so build your client to handle a 429 rather than to stay under a number. The v1 API does publish one, and it is per token (see the aside below).

Handling a 429

A 429 says to slow down, not that the request was wrong. Don’t change the request; wait and send it again. Exponential backoff with jitter is the usual shape. Retrying at once in a tight loop only keeps you throttled.

Outside v1, a 429 carries the usual google.rpc.Status body, with code 8. See Errors.

If you are paging a long list, a larger pageSize moves more records per request. That is a better lever than a higher request rate. See Pagination.

Legacy (v1)

The v1 API rate-limits with a leaky bucket. The bucket drains at 10 requests per second and absorbs a burst of 10 on top of that. A request over the limit is answered 429 at once; it is not queued. The bucket refills at a tenth of a second per request.

The limit is per API token. Each token gets its own bucket, so one integration’s traffic does not eat another’s headroom, and two tokens in the same account are counted separately. An older version of this page said the limit was shared across all incoming requests. That was wrong.

Requests with no Authorization header share a single bucket. The limit keys on that header, so every unauthenticated request competes for one bucket. Once you send a token, you are in your own.

A throttled v1 request never reaches the application, so the body comes from the edge:

{ "errorCode": "429", "errorMessage": "Rate Limit Exceeded" }

The message is under errorMessage, singular. There is no referenceId, so quote the time and the token to support instead. On v1, a larger pageLength is the lever for long lists.