429 Too Many Requests with the number of seconds to wait. Pace your client with the headers and you rarely see a 429 at all.
How it works
Two limits apply, each with its own quota and window:- An upload request counts against both:
file-uploadis checked first, thendefault. An upload rejected byfile-uploadnever reachesdefault. - Each request costs one, whatever it contains. A batch upload registering 100 files costs the same as a single upload, so batching is the cheapest way to send many files.
- Requests are counted per project. Every API key on the same project draws on the same allowance.
- The window is fixed: it starts with the first request, and the full allowance returns when it ends. It does not refill gradually.
Headers
Every authenticated response carries these headers, success or error:
Read your actual quota and window from
RateLimit-Policy; they can differ between projects.
The 429 response
A request over a limit is rejected before it runs, so nothing is created or changed. The body is a problem document with codeRATE_LIMITED and a retryAfter member that matches the Retry-After header:
429 Too Many Requests
detail is File upload rate limit exceeded when the file-upload limit was hit. Branch on code, not detail. The RateLimit header on a 429 describes the limit that was breached.
Back off
1
Watch the headers
Parse
RateLimit on every response. When r gets low, spread the remaining requests over the t seconds left instead of sending them at once.2
On a 429, wait Retry-After
Sleep for
Retry-After seconds (or retryAfter from the body), then retry the same request. Waiting longer is fine; retrying sooner just earns another 429.3
Make retries safe
Send an
Idempotency-Key on writes. A 429 is never stored against the key, so the retry runs normally.Related
Errors
Problem documents, codes and when to retry.
Idempotent requests
Retry writes without applying them twice.
Uploads
Batch uploads cost one request for up to 100 files.
Troubleshooting
Common failures and how to fix them.