Rate Limiting
The Partner API caps how many requests one partner account sends per minute. A request over the cap is rejected, not queued.
The cap covers every Partner API endpoint. It applies to the partner account, so two client credentials under one account draw on the same budget.
A rejected request
| Surface | Response |
|---|---|
| REST | 429 Too Many Requests |
| gRPC | RESOURCE_EXHAUSTED |
A rejected request does no work. No job is created, and no image is read.
Read the limit from the response
A rate limit response carries three headers:
| Header | Value |
|---|---|
X-RateLimit-Limit | requests allowed in the current window |
X-RateLimit-Remaining | requests left in the current window |
X-RateLimit-Reset | Unix timestamp in seconds when the window resets |
Read X-RateLimit-Reset and wait until that time. The timestamp is exact, so it recovers sooner than a fixed backoff and it never retries early.
Recover from a rejection
- Stop sending requests on the account.
- Wait until the time in
X-RateLimit-Reset. - Retry the request once.
- On a second rejection, double the wait. Stop after four attempts.
An immediate retry spends the next window, so the lockout gets longer.
If the response carries no X-RateLimit-Reset header, wait 60 seconds before the first retry. Double the wait on each further rejection.
Stay under the cap
- Read
X-RateLimit-Remainingon every response. Slow down before it reaches zero. - Cache the access token and reuse it until it expires. See Handle Token Expiration.
- Replace status polling with callbacks. Polling one job every second spends 60 requests a minute on that job alone.