Limits

Daytona v2

Documentation for Daytona v2, currently in alpha. For the latest release, see Daytona v0.

Daytona enforces three kinds of limits: sandbox limits, which cap the resources a single sandbox can reserve, organization limits, which cap how many sandboxes and image builds an organization can hold at once, 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.

Resource	Unit	Default	Minimum	Maximum
CPU	vCPU	0.125	0.125	16
Memory	MiB	1024	512 (when set explicitly)	32768
Disk	MiB	512	10240 (when set explicitly)	262144

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. Guaranteed CPU is also raised to at least one core per 4 GiB of guaranteed memory. A sandbox may additionally set per-sandbox limits on vCPUs (between 1 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.

Organization limits

Organization limits cap the number of sandboxes and image builds across every project in an organization. Each limit is set per organization; an unset limit imposes no cap.

Limit	What it counts	Checked on
max_concurrent_vms	Sandboxes that hold or are about to hold compute: pending, building, booting, running, pausing, stopping, or deleting	Create, fork, snapshot restore, start, resume
max_total_vms	Concurrent sandboxes plus stopped and paused sandboxes. Deleted and failed sandboxes do not count	Create, fork, snapshot restore
max_concurrent_builds	Image builds that are pending or building	Image build

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

Daytona includes rate limit information in the response headers of every authenticated request. The header names carry an authenticated suffix, which identifies the rate limit bucket:

Header	Description
X-RateLimit-Limit-authenticated	Maximum number of requests allowed in the time window
X-RateLimit-Remaining-authenticated	Number of requests remaining in the current window
X-RateLimit-Reset-authenticated	Time in seconds until the rate limit window resets
Retry-After	Time in seconds to wait before retrying (included only on 429 responses)

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.

code	Cause	Retry
RATE_LIMITED	The request rate limit for the project, organization, user, or sandbox was exceeded	Wait for the seconds in Retry-After, then retry
RATE_LIMITED	Too many requests with invalid credentials from the same IP address; the message is too many failed authentication attempts	Fix the credentials; the block lifts after the seconds in Retry-After
OVERLOADED	The sandbox creation queue or the organization’s admission queue is at capacity (returned by sandbox create, fork, start, resume, and image build)	Wait for the seconds in Retry-After, then retry
LIMIT_EXCEEDED	An organization limit is reached	Stop or delete sandboxes, or wait for builds to finish; the response carries no Retry-After
TOO_MANY_REQUESTS	A generic 429 with no more specific code	Wait for the seconds in Retry-After when present, then retry

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

Property	Description
code	The error code.
message	The error message.
source	The component that produced the error, DAYTONA_API.
retry_after_seconds	Seconds to wait before retrying, also sent as the Retry-After header. Present on RATE_LIMITED and OVERLOADED responses.
limit	On LIMIT_EXCEEDED responses, the limit hit, such as max_concurrent_vms.
current	The organization’s current count for limit. Present on LIMIT_EXCEEDED responses.
max	The organization’s value for limit. Present on LIMIT_EXCEEDED responses.
trace_id	The request trace ID.

{
  "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 LIMIT_EXCEEDED response raises LimitExceededError, a subclass of the rate limit error that also exposes limit, current, and max. All SDK errors expose the HTTP status code, the error code, and the message:

Python

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)

• The SDK does not retry a 429 response.
• Read retry_after_seconds on the error for the seconds to wait.
• The SDK sets retry_after_seconds on rate limited and overloaded errors.
• RateLimitedError and OverloadedError subclass RateLimitError.
• A handler can catch each retryable condition separately.
• e.code is RATE_LIMITED, OVERLOADED, or LIMIT_EXCEEDED.

TypeScript

import { Daytona } from '@daytona/sdk'
import { LimitExceededError, RateLimitError } from '@daytona/sdk/v2'

const daytona = new Daytona()

try {
  await daytona.v2.createFromSnapshot('my-snapshot')
} catch (error) {
  if (error instanceof LimitExceededError) {
    console.log(error.limit, error.current, error.max)
  } else if (error instanceof RateLimitError) {
    console.log(error.statusCode, error.code, error.message)
  }
}

• The SDK does not retry a 429 response.
• Read retryAfterSecs on the error for the seconds to wait.
• The SDK sets retryAfterSecs on rate limited and overloaded errors.
• RateLimitedError and OverloadedError extend RateLimitError.
• A handler can catch each retryable condition separately.
• error.code is RATE_LIMITED, OVERLOADED, or LIMIT_EXCEEDED.

API

# Rate limit headers are returned on every authenticated response
curl -i 'https://api.daytona.com/sandboxes' \
  --header 'Authorization: Bearer YOUR_API_KEY'

HTTP/1.1 200 OK
x-ratelimit-limit-authenticated: 100
x-ratelimit-remaining-authenticated: 97
x-ratelimit-reset-authenticated: 42

HTTP/1.1 429 Too Many Requests
retry-after: 42
x-ratelimit-limit-authenticated: 100
x-ratelimit-remaining-authenticated: 0
x-ratelimit-reset-authenticated: 42

Best practices

Handle 429 responses by waiting for the number of seconds in the Retry-After header (or the retry after seconds field in 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 (X-RateLimit-Remaining-authenticated and X-RateLimit-Reset-authenticated) to track consumption and throttle proactively before reaching the limit.

Distinguish RATE_LIMITED from OVERLOADED. A RATE_LIMITED response means your project sent too many requests; slow down the caller. An OVERLOADED response means the platform’s sandbox creation 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; only deleting sandboxes frees max_total_vms slots. Build slots free when image builds finish.

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

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