Skip to main content

Sandbox errors

Private preview

Sandboxes are in private preview, by invitation: they are enabled on request for existing Serenity Edge customers and partners (see Access). New error codes may be added during the preview; they will be announced in the 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: both are served on https://api.serenityedge.ai, but the sandbox paths (/sandboxes, /v2/sandboxes and the others of the API reference) 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).

{
"code": 429,
"error_code": "edge_concurrency_limit",
"message": "This key may run at most 48 sandboxes in this site"
}
FieldMeaning
codeThe HTTP status, repeated.
error_codeMachine-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.
messageHuman-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​

Statuserror_codeWhenWhat to do
401edge_unauthorizedThe 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.
403edge_sandboxes_not_enabledThe 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).
403edge_site_not_enabledThe 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).
403edge_sandbox_not_ownedOnly 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.

Statuserror_codeWhenWhat to do
400edge_invalid_requestThe 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.
400edge_field_not_supportedA 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.
400edge_metadata_too_largeThe metadata of a create is over 4,096 bytes.Send less metadata. It is never truncated.
400edge_shape_limitA 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.
400edge_egress_off_not_availableA 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).Retry later, or leave allow_internet_access out if the sandbox may have internet access.
400edge_upgrade_not_supportedThe request asks to switch protocols (Upgrade) on the control API.Send a plain HTTP request.
403edge_metadata_reservedA metadata key starts with serenity. or edge..Rename the key.
403edge_template_not_allowedThe 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), or check the snapshot id with list_snapshots.
403edge_template_builds_disabledA 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).
403edge_egress_managedThe 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.
403edge_public_traffic_not_supportedA 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.
403edge_logs_not_availableGET /sandboxes/{sandboxID}/logs or its /v2 form. Sandbox logs are not available in the preview.Capture the output of your commands in your client.
404edge_route_not_availableThe 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.
413edge_request_too_largeThe request body is over 1 MiB.Send a smaller body.

Limits, capacity and availability​

Retry these, after waiting.

Statuserror_codeWhenWhat to do
429edge_concurrency_limitYour 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.
429edge_create_rate_limitYour 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.
429edge_key_concurrency_limitOnly 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.
429edge_key_create_rate_limitOnly 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.
429edge_key_request_concurrency_limitThis key already has 8 requests to the control API in flight, sent and not yet answered (see Request limits).Wait for Retry-After, then retry. Send fewer control calls at once.
429edge_key_request_rate_limitThis 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.
429edge_sandbox_api_busyThe 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.
429edge_upstream_rate_limitedThe 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.
503edge_upstream_unavailableThe 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 before creating again.
503edge_upstream_timeoutThe 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.
503sandbox_capacity_unavailableCapacity: 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.
503none, or another code of the runtimeThe 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:

StatusWhenWhat to do
404The sandbox does not exist, was killed or has expired, or belongs to another account.Do not retry.
409The 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 foundA 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 [email protected].
500, otherAn 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).

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.