API

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 429 after Retry-After, and 502, 503 and 504 with 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, 410 or 422 unchanged. They will answer the same.
  • GET, PUT and DELETE are safe to repeat. A POST that 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.