Limits and retries
Two kinds of limit apply to the API: rate limits on how fast you call it, and plan quotas on how much you run.
Rate limits
Endpoints are rate limited. Over the limit, the API answers 429 with a Retry-After header in seconds and the code rate_limited. Wait at least that long before you retry.
Some endpoints with a cost, such as starting sandboxes or minting credentials, have their own lower limits.
Plan quotas
Your plan sets how many boxes run at once, the vCPU per box, build host lease hours, object storage and how many vCPU-hours are included each month. The plans reference lists them, generated from the plan catalogue the server enforces.
A request that would go over a quota is refused before anything starts, with quota_exceeded (402 or 429 depending on the endpoint). Your organization’s quotas and usage are under Projects, quotas and regions, where you can also ask for an increase.
Retrying safely
- Retry
429afterRetry-After, and502,503and504with exponential backoff and jitter: wait 1, 2, 4, 8 seconds and so on, up to a minute. - Do not retry
400,401,403,404,409,410or422unchanged. They will answer the same. GET,PUTandDELETEare safe to repeat. APOSTthat creates something (a sandbox, a lease) is not always: after a timeout, list what exists before you create it again.
Streams
Long-running output, such as sandbox logs and agent task logs, is streamed. Read it as it arrives rather than waiting for the response to end.