# Sandbox errors

> Every HTTP status and edge_ error code of the Serenity Edge sandbox API, what each one means, and whether to retry.

Source: https://docs.serenityedge.ai/docs/sandboxes/errors/

> **Private preview**
> 
> Sandboxes are in private preview, by invitation: they are enabled on request for existing Serenity Edge customers and partners (see [Access](https://docs.serenityedge.ai/docs/sandboxes/overview/#access)). New error codes may be added during the preview; they will be announced in the [release notes](https://docs.serenityedge.ai/release-notes/).

## Error object

The sandbox API answers errors in the shape of the E2B API, so the E2B SDKs raise their usual exceptions. It is not the OpenAI error shape of the [inference API](https://docs.serenityedge.ai/docs/errors-and-rate-limits/): both are served on `https://api.serenityedge.ai`, but the sandbox paths (`/sandboxes`, `/v2/sandboxes` and the others of the [API reference](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#endpoints)) answer in the E2B shape and the inference paths under `/v1` in the OpenAI shape. `GET /v1/usage`, which returns your sandbox usage records, is under `/v1` and answers in the OpenAI shape (see [Check your usage](https://docs.serenityedge.ai/docs/sandboxes/pricing-and-usage/#check-your-usage)).

```json
{
  "code": 429,
  "error_code": "edge_concurrency_limit",
  "message": "This key may run at most 48 sandboxes in this site"
}
```

| Field | Meaning |
| --- | --- |
| `code` | The HTTP status, repeated. |
| `error_code` | Machine-readable code. Codes that start with `edge_` are Serenity Edge's own and are listed on this page. Any other code, or none, comes from the sandbox runtime and has its E2B meaning. |
| `message` | Human-readable description. Safe to log; do not show it to end users verbatim. |

Two headers tell a client what to do:

-   `Retry-After`: the number of seconds to wait before retrying. Sent with every 429 on this page, and with some 503 answers.
-   `Should-Retry: false`: sent with some refusals that no retry can change, and with a timeout of a call that may have taken effect. The E2B SDKs read it and do not retry the call by themselves.

## Error codes

### Authentication and access

| Status | `error_code` | When | What to do |
| --- | --- | --- | --- |
| 401 | `edge_unauthorized` | The key is missing, unknown or revoked, or it is not a Serenity Edge API key. With `E2B_DOMAIN` set to the site's domain (the setting of 12 November), also a key whose account does not have Sandboxes enabled. | Check the `X-API-Key` header and the key. See [Access](https://docs.serenityedge.ai/docs/sandboxes/overview/#access). |
| 403 | `edge_sandboxes_not_enabled` | The key is a valid Serenity Edge API key, but its account does not have Sandboxes enabled. The same key works for inference. | Ask for Sandboxes to be enabled on your account (see [Access](https://docs.serenityedge.ai/docs/sandboxes/overview/#access)). |
| 403 | `edge_site_not_enabled` | The key's account has Sandboxes enabled, but not on the site that would serve the call. | Set `E2B_DOMAIN` to `serenityedge.ai`. If you already do, ask for Sandboxes to be enabled on your account (see [Access](https://docs.serenityedge.ai/docs/sandboxes/overview/#access)). |
| 403 | `edge_sandbox_not_owned` | Only on accounts whose keys are kept apart: the sandbox was created with another key of your account. | Use the key that created the sandbox. |

### Requests that are refused

Do not retry these as they are: change the request. The codes of saving a sandbox as a template, such as `edge_template_limit`, are listed on [Save a sandbox as a template](https://docs.serenityedge.ai/docs/sandboxes/templates/#errors).

| Status | `error_code` | When | What to do |
| --- | --- | --- | --- |
| 400 | `edge_invalid_request` | The body could not be read or is not a JSON object, a field has the wrong type or an invalid value (for example `templateID` missing, a negative `timeout`, a `cpuCount` or `memoryMB` below 1, a fork `count` outside 1 to 100), or the same field appears twice in different letter case. | Fix the body. The message names the field. |
| 400 | `edge_field_not_supported` | A create carries a field that Serenity Edge does not support, for example `volumeMounts`, `mcp`, `iam`, `secure: false`, `autoPauseMemory: false` or `autoResume.enabled: true`. Only the fields of the allow-list are accepted. | Remove the field. The message names it. See [Create fields](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#create-fields). |
| 400 | `edge_metadata_too_large` | The metadata of a create is over 4,096 bytes. | Send less metadata. It is never truncated. |
| 400 | `edge_shape_limit` | A create asks for a `cpuCount` or `memoryMB` that is not the template's, the template is larger than your account's maximum size, or a resume asks for more vCPUs than your account's maximum. | Leave `cpuCount` and `memoryMB` out. |
| 400 | `edge_egress_off_not_available` | A create sets `allow_internet_access: false` while the site cannot create sandboxes with no internet access. Not expected in the preview, where they are available (see [Sandboxes with no internet access](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#sandboxes-with-no-internet-access)). | Retry later, or leave `allow_internet_access` out if the sandbox may have internet access. |
| 400 | `edge_upgrade_not_supported` | The request asks to switch protocols (`Upgrade`) on the control API. | Send a plain HTTP request. |
| 403 | `edge_metadata_reserved` | A metadata key starts with `serenity.` or `edge.`. | Rename the key. |
| 403 | `edge_template_not_allowed` | The `templateID` of a create is not a template your account may use: the public template, or one of your account's own templates when they are enabled. | Use the public template (see [Templates](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#templates)), or check the snapshot id with `list_snapshots`. |
| 403 | `edge_template_builds_disabled` | A template build or change. On an account without templates enabled, also `POST /sandboxes/{sandboxID}/snapshots` and the delete of a template. | Use the public template, or ask for templates to be enabled (see [Save a sandbox as a template](https://docs.serenityedge.ai/docs/sandboxes/templates/)). |
| 403 | `edge_egress_managed` | The request sets outbound network rules: `network.allowOut`, `denyOut`, `dnsServers`, `rules` or `egressProxy` on create, `allow_internet_access: true`, any network field on fork, resume or connect, or `PUT /sandboxes/{sandboxID}/network`. | Remove the setting. Outbound access is set by Serenity Edge, the same for every account. See [Outbound access](https://docs.serenityedge.ai/docs/sandboxes/network-and-security/#outbound-access). |
| 403 | `edge_public_traffic_not_supported` | A create sets `network.allowPublicTraffic: true`. Public sandbox URLs are not available in the preview. | Leave it out and send the sandbox's traffic access token with each request to a port. |
| 403 | `edge_logs_not_available` | `GET /sandboxes/{sandboxID}/logs` or its `/v2` form. Sandbox logs are not available in the preview. | Capture the output of your commands in your client. |
| 404 | `edge_route_not_available` | The route is not part of the sandbox API on Serenity Edge, or the path has an empty, dot or percent-encoded segment. | Check the path against the [supported endpoints](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#endpoints). |
| 413 | `edge_request_too_large` | The request body is over 1 MiB. | Send a smaller body. |

### Limits, capacity and availability

Retry these, after waiting.

| Status | `error_code` | When | What to do |
| --- | --- | --- | --- |
| 429 | `edge_concurrency_limit` | Your account already runs its maximum number of sandboxes (48 in the preview). Returned on create, fork, resume, and connect to a paused sandbox. The message states the limit. | Wait for `Retry-After`, or kill or pause a sandbox first. A sandbox that could not be resumed stays paused. |
| 429 | `edge_create_rate_limit` | Your account created its maximum number of sandboxes in the last 60 seconds (60 in the preview). A fork of `n` copies counts as `n` creates. The message states the limit. | Wait for `Retry-After`, then retry. |
| 429 | `edge_key_concurrency_limit` | Only on accounts with limits per key: this key already runs its maximum number of sandboxes. The other keys of the account have their own. The message states the limit. | Wait for `Retry-After`, or kill or pause a sandbox of this key. |
| 429 | `edge_key_create_rate_limit` | Only on accounts with limits per key: this key created its maximum number of sandboxes in the last 60 seconds. The message states the limit. | Wait for `Retry-After`, then retry. |
| 429 | `edge_key_request_concurrency_limit` | This key already has 8 requests to the control API in flight, sent and not yet answered (see [Request limits](https://docs.serenityedge.ai/docs/sandboxes/limits-and-quotas/#request-limits)). | Wait for `Retry-After`, then retry. Send fewer control calls at once. |
| 429 | `edge_key_request_rate_limit` | This key sent 120 requests to the control API in the last 60 seconds. Every control call counts, reads and lists included. | Wait for `Retry-After`, then retry. Poll less often. |
| 429 | `edge_sandbox_api_busy` | The control API as a whole is busy for a moment, while your key is under its own limits. | Wait for `Retry-After`, then retry with backoff. |
| 429 | `edge_upstream_rate_limited` | The sandbox service is briefly limiting the calls it accepts from the API. Not caused by your key. | Wait for `Retry-After`, then retry with backoff. |
| 503 | `edge_upstream_unavailable` | The sandbox service could not be reached, or did not give a valid answer. With `E2B_DOMAIN` set to the site's domain, the same code comes with HTTP 502. | Wait for `Retry-After`, then retry with backoff. A create or resume that got this answer may still have taken effect: [list your sandboxes](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#retrying-a-create) before creating again. |
| 503 | `edge_upstream_timeout` | The sandbox service did not answer within 90 seconds. A call that is not a read (`GET`) gets `Should-Retry: false` instead of `Retry-After`, because it may have taken effect. | Read or list the sandbox before you repeat a create, pause, connect or kill. Retry a read with backoff. |
| 503 | `sandbox_capacity_unavailable` | Capacity: the site has no room for another sandbox right now. A create, a fork or a resume (a connect to a paused sandbox) can get it, even when your account is under its own limits. A refused resume leaves the sandbox paused. | Retry later with exponential backoff, over minutes rather than seconds, and wait for `Retry-After` when the answer carries it. Kill or pause the sandboxes you no longer need. |
| 503 | none, or another code of the runtime | The service is restarting or briefly unavailable. | Wait for `Retry-After` when the answer carries it, then retry with backoff. |

## Errors from the sandbox runtime

Answers without an `edge_` code come from the sandbox runtime unchanged and mean what they mean in the E2B API. The ones you are most likely to see:

| Status | When | What to do |
| --- | --- | --- |
| 404 | The sandbox does not exist, was killed or has expired, or belongs to another account. | Do not retry. |
| 409 | The sandbox is not in the state the call needs, for example a resume of a sandbox that is already running. | Read the sandbox's state and decide again. |
| 500 with a message that the sandbox's files were not found | A resume of a paused sandbox whose stored memory and disk could not be read. | Retry a few times over the next minutes; the sandbox stays paused meanwhile. If it keeps failing, kill the sandbox and write to [contact@substrate.ai](mailto:contact@substrate.ai). |
| 500, other | An unexpected error. | Retry with backoff. |

## Handling 429 and 503

1.  Read `Retry-After` when the answer carries it, and wait at least that long.
2.  Retry with exponential backoff and jitter, and cap the number of attempts.
3.  Before retrying a create whose answer you did not receive, list your sandboxes by metadata: a create is not idempotent (see [Retrying a create](https://docs.serenityedge.ai/docs/sandboxes/api-reference/#retrying-a-create)).

`503 sandbox_capacity_unavailable` means that the site is full for the moment, not that your request or your account is at fault: room comes back as sandboxes end or pause, so space your retries over minutes. A 503 that persists across retries means the service is at capacity or has an incident, not a problem with your request.
