How does quotaUser work?

Question

I'm experiencing a lot of 429 "Too many requests" errors when downloading data from a large number of sheets. Specifically, I run into the USER-100s rate limit.

As per the documentation, I'm trying to use the quotaUser query parameter with a random value for every request in order to bypass the user limit and only be subjected to the project limit instead, which is 500 requests per 100 seconds.

However, I do not see a difference with regards to the rate limit whether or not I use the quotaUser parameter.

With the following little test snippet (URL being a Sheets API endpoint):

def run(url, use_quota_user=False):
    for i in range(200):
        headers = {
            'Authorization': 'Bearer %s' % ACCESS_TOKEN
        }
        if use_quota_user:
            _url = '%s&quotaUser=%s' % (url, str(uuid.uuid4()))
        else:
            _url = url
        resp = requests.get(_url, headers=headers)
        if resp.status_code == 200:
            pass
        elif resp.status_code == 429:
            print('Quota exhausted with request %d: %s' % (i, resp.json()['error']['message']))
            break
        else:
            print('Received error, aborting: %s' % resp.json()['error']['message'])
            return


def main():
    print('Running without quotaUser...')
    run(URL, use_quota_user=False)
    time.sleep(100)
    print('Running with quotaUser...')
    run(URL, use_quota_user=True)

I get (almost) the exact same behavior with and without quotaUser:

Running without quotaUser...
Quota exhausted with request 103: Insufficient tokens for quota 'ReadGroup' and limit 'USER-100s' [...]
Running with quotaUser...
Quota exhausted with request 105: Insufficient tokens for quota 'ReadGroup' and limit 'USER-100s' [...]

Am I doing something wrong? How can I properly utilize the quotaUser parameter so that I don't hit the USER-100s limit?

Answer 1

Google's documentation was updated in February 2021 to clarify this.

In a nutshell, quotaUser can only be used when authenticating a request via API key. If an OAuth2 access token or similar authentication material is provided, the authenticated principal is used to check the user quota, and quotaUser is silently ignored.