Limits

Daytona enforces three kinds of limits: sandbox limits, which cap the resources a single sandbox can reserve, organization limits, which cap how many sandboxes, image builds, volumes, images, snapshots, members, secrets, and API keys an organization can hold, and rate limits, which cap how many API requests a project can make within a time window. For information on spending and wallet management, see billing.

Sandbox limits

Sandbox limits cap the CPU, memory, and disk a single sandbox can reserve. The limits apply per sandbox, not as a shared pool across the organization.

A create request that reserves more than the maximum on any axis is rejected with a 400 error that names the exceeded cap. Requests below the minimum are raised to the minimum. The minimums apply once a create sets any of CPU, memory, or disk; a create that sets none keeps the defaults. A request raised above a limit set in the same create is rejected with a 400 error. Guaranteed CPU is also raised to at least one core per 8 GiB of guaranteed memory. A sandbox may additionally set per-sandbox limits on cores (a multiple of 0.5, between 0.5 and 16), memory in MiB (between 256 and 32768), and disk in MiB (between 512 and 262144), which can only lower the boot shape below the platform maximum. See sandbox resources.

The plan of the organization can cap the cores and memory of a Linux sandbox below the platform maximum:

The Enterprise caps are above the platform maximum, so the platform maximum applies. The plan caps apply to both the guarantee and the per-sandbox limits. A request above a plan cap is rejected with a 400 error that names the plan limit, and an omitted per-sandbox limit defaults to the plan cap. The plan response reports the core and memory caps of the organization.

Organization limits

Organization limits cap the number of sandboxes, image builds, volumes, images, snapshots, and members across every project in an organization, and the number of secrets and API keys. Each limit is a ceiling, not a reservation: reaching it refuses new work, but nothing is set aside. A request that would exceed a limit is rejected with a 429 error with the code LIMIT_EXCEEDED that names the limit, the current count, and the maximum.

Get organization limits

Daytona provides methods to get the limits of an organization and the current usage counted against each one. Each limit in the response carries the effective cap and the current usage. When no limit applies, the cap is null. An API key reads the limits of its own organization, and its response leaves out the member counts.

from daytona import Daytona

daytona = Daytona()
limits = daytona.v2.get_limits()
print(limits.sandboxes.concurrent.usage, limits.sandboxes.concurrent.limit)

Rate limits

Rate limits control how many API requests you can make within a fixed 60 second window. Requests authenticated with an API key are counted per project: every API key in a project draws on the same budget, so adding keys does not raise the limit.

Requests are counted per organization with an organization API key, per user from the Daytona Dashboard, and per sandbox with a sandbox-scoped token.

Daytona also blocks a client IP address for a window after repeated requests with invalid credentials. Requests that carry a valid API key are not affected by this block.

Rate limit headers

When Daytona enforces the request rate limit, it includes rate limit information in the response headers of every authenticated request. A response without these headers was not counted against the request rate limit. The header names carry an authenticated suffix, which identifies the rate limit bucket:

Rate limit errors

Daytona returns HTTP 429 Too Many Requests for the following conditions. The code field in the response body identifies the condition. Use it, not the presence of headers, to decide how to react.

The error response is a JSON object with the following properties:

{
  "code": "RATE_LIMITED",
  "message": "request rate limit exceeded; retry after the indicated delay",
  "source": "DAYTONA_API",
  "retry_after_seconds": 42,
  "trace_id": "0af7651916cd43dd8448eb211c80319c"
}

The Python and TypeScript SDKs raise or throw a rate limit error for every 429 response, including the overloaded condition. A response for an exceeded limit raises a subclass of the rate limit error that also exposes the limit, the current usage, and the maximum. All SDK errors expose the HTTP status code, the error code, and the message:

from daytona import Daytona
from daytona.v2 import LimitExceededError, RateLimitError

daytona = Daytona()

try:
    daytona.v2.create_from_snapshot("my-snapshot")
except LimitExceededError as e:
    print(e.limit, e.current, e.max)
except RateLimitError as e:
    print(e.status_code, e.code, e.message)

Best practices

Best practices keep a client within its limits and help it recover when a request is refused.

• Wait before retrying a 429 response. Wait for the number of seconds in the Retry-After header, or in the retry_after_seconds field of the body, before retrying. If a retry is rejected again, back off exponentially (1s, 2s, 4s, 8s, and so on) instead of retrying at a fixed interval.

• Monitor rate limit headers. The rate limit headers X-RateLimit-Remaining-authenticated and X-RateLimit-Reset-authenticated track how much of the budget is left in the current window. Throttle the client before it reaches the limit, and do not treat a response without these headers as an error.

• Distinguish RATE_LIMITED from OVERLOADED. A RATE_LIMITED response means the project, organization, user, or sandbox sent too many requests; slow down the caller. An OVERLOADED response means the sandbox creation queue or the organization's admission queue is full; retry after the delay without reducing your request rate elsewhere.

• Do not retry LIMIT_EXCEEDED on a timer. The request succeeds only after the count for the named limit drops below max. Stopping or deleting sandboxes frees concurrent slots once the sandbox leaves the stopping or deleting state; only deleting sandboxes frees max_total_vms slots. Build slots free when image builds finish. Deleting volumes, images, or snapshots frees their slots.

• Cache API responses. Cache responses that change infrequently, such as sandbox lists, available regions, and snapshot information, to avoid unnecessary requests.

• Avoid tight polling loops. Poll for state changes at an interval within the remaining budget, and monitor your logs for 429 errors to catch rate limiting before it affects users.

Permissions

Organization limits can be read with a project API key or by a signed-in member.

Every role includes the organization read permission.