# Limits Daytona enforces three kinds of limits: [sandbox limits](#sandbox-limits), which cap the resources a single sandbox can reserve, [organization limits](#organization-limits), which cap how many sandboxes and image builds an organization can hold at once, and [rate limits](#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](https://www.daytona.io/docs/en/v2/billing.md). ## 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](https://www.daytona.io/docs/en/v2/sandboxes.md#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](https://www.daytona.io/docs/en/v2/api-keys.md) 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](https://www.daytona.io/docs/en/v2/api-keys.md#organization-api-keys), 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](#organization-limits) 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. | ```json { "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](https://www.daytona.io/docs/en/v2/python-sdk.md) and [TypeScript](https://www.daytona.io/docs/en/v2/typescript-sdk.md) 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`**. ```bash # Rate limit headers are returned on every authenticated response curl -i 'https://api.daytona.com/sandboxes' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```text HTTP/1.1 200 OK x-ratelimit-limit-authenticated: 100 x-ratelimit-remaining-authenticated: 97 x-ratelimit-reset-authenticated: 42 ``` ```text 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](#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](https://www.daytona.io/docs/en/v2/sandboxes.md#list-sandboxes), [available regions](https://www.daytona.io/docs/en/v2/regions.md), and [snapshot information](https://www.daytona.io/docs/en/v2/snapshots.md), 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.