> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

Every error the Agent Sandboxes API returns has an HTTP status and a code. Errors use the Telnyx error envelope. `title` is the error's name, and `source` points at the field or parameter at fault.

```json Output theme={null}
{
  "errors": [
    {
      "code": "90001",
      "title": "resources_not_allowed",
      "detail": "memory_mib 8192 is above the largest size, 4096",
      "source": { "pointer": "/memory_mib" }
    }
  ]
}
```

A `503` carries a `Retry-After` header.

## Sandbox Errors

| Status | Code | Title | Cause |
| - | - | - | - |
| 401 | `90029` | `invalid_token` | The token is missing, expired, or not valid. |
| 403 | `90030` | `invalid_identity` | The token carries no usable organization. |
| 409 | `90010` | `name_conflict` | A live sandbox or template already has the name. |
| 409 | `90011` | `request_in_progress` | A request with the same `Idempotency-Key` is still running. |
| 409 | `90012` | `sandbox_not_running` | The operation needs a `running` sandbox. |
| 409 | `90013` | `exec_not_running` | The exec has ended. |
| 409 | `90014` | `path_type_mismatch` | The path is a directory where a file was expected, or the reverse. |
| 409 | `90015` | `directory_not_empty` | The directory has contents and `recursive` was not set. |
| 409 | `90021` | `operation_in_progress` | A pause, a snapshot, or a template build is in progress. |
| 409 | `90022` | `snapshot_not_published` | The snapshot is not yet usable. |
| 409 | `90025` | `source_terminated` | The snapshot's source sandbox has terminated. |
| 409 | `90032` | `sandbox_paused` | Execs and files need a running sandbox. Send `connect`. |
| 409 | `90033` | `invalid_state` | The sandbox's state does not allow the operation. |
| 409 | `90035` | `cross_device` | A rename crosses filesystems. |
| 409 | `90037` | `no_command` | The sandbox has no main command. |
| 409 | `90039` | `sandbox_terminated` | The sandbox has terminated. |
| 409 | `90040` | `snapshot_quota` | The sandbox already holds three snapshots. |
| 409 | `90043` | `template_not_ready` | The template is not `ready`. |
| 410 | `90046` | `logs_expired` | The sandbox's logs are no longer kept. |
| 413 | `90016` | `file_too_large` | The file is over 512 MiB. |
| 422 | `90001` | `resources_not_allowed` | A size is outside the allowed values. |
| 422 | `90002` | `registry_not_allowed` | The image reference does not name a public registry host. |
| 422 | `90003` | `invalid_env` | An environment variable is invalid or too large. |
| 422 | `90004` | `invalid_workdir` | `workdir` is not an absolute path. |
| 422 | `90005` | `invalid_command` | The command is empty or too large. |
| 422 | `90006` | `invalid_path` | The file path is invalid or reserved. |
| 422 | `90007` | `cidr_not_allowed` | An `allow_out` entry overlaps the deny set. |
| 422 | `90009` | `idempotency_key_reused` | The `Idempotency-Key` was used for a different request. |
| 422 | `90026` | `invalid_egress_rule` | A secret rule's host, header, or template is invalid. |
| 422 | `90027` | `unknown_secret` | A named secret does not exist. |
| 422 | `90028` | `rules_not_allowed` | Secret rules are not allowed under `blocked`. |
| 422 | `90031` | `wrong_region` | `region` names another region than the API's. |
| 422 | `90034` | `unknown_user` | The exec's `user` does not exist in the image. |
| 422 | `90036` | `allow_out_not_allowed` | `allow_out` is set without `allowlist`. |
| 422 | `90038` | `rules_immutable` | A network change alters `rules`. |
| 422 | `90041` | `template_field_conflict` | A field is set beside `template` that the template defines. |
| 422 | `90042` | `unknown_template` | The template does not exist or was deleted. |
| 422 | `90044` | `template_env_secret` | A template's `env` holds a secret marker. |
| 429 | `90017` | `quota_exceeded` | The organization is at its sandbox or template quota. |
| 500 | `90020` | `internal_error` | The platform failed. |
| 503 | `90019` | `no_capacity` | No host in the region has room. |
| 503 | `90045` | `secrets_unavailable` | The organization's secrets could not be read. |

## Port Errors

A request to a [port URL](https://developers.telnyx.com/docs/edge-compute/sandboxes/out-of-band-access/ports.md) that the platform refuses carries the error in its body and the error's title in a `Telnyx-Sandbox-Error` response header.

| Status | Code | Title | Cause |
| - | - | - | - |
| 403 | `90049` | `port_refused` | The port is `49983`, which the platform reserves. |
| 403 | `90050` | `traffic_token_required` | The sandbox's ports are not public, and the request carries no valid `Telnyx-Sandbox-Traffic-Token`. |
| 502 | `90047` | `port_closed` | Nothing in the sandbox listens on the port. |
| 502 | `90048` | `port_unreachable` | The sandbox did not answer the connection to the port. |
| 503 | `90051` | `too_many_connections` | More than 256 connections are open to the sandbox's ports. |

A port on a sandbox that is not `running` answers `502` with the `sandbox_not_running` body.

## General Errors

| Status | Code | Title | Cause |
| - | - | - | - |
| 400 | `10004` | `missing_parameter` | A required field is missing. |
| 400 | `10015` | `bad_request` | The request is malformed, or names an unknown field. |
| 400 | `10025` | `invalid_string_length` | A string is too short or too long. |
| 400 | `10026` | `invalid_type` | A field has the wrong type. |
| 404 | `10005` | `not_found` | The resource does not exist or belongs to another organization. |
| 405 | `10015` | `method_not_allowed` | The route does not accept the method. |
| 413 | `10015` | `request_too_large` | The request body is over 1 MiB. |
| 429 | `10011` | Too many requests | The API key sent more than 20 requests to the control plane in one second. |
| 503 | `10037` | `service_unavailable` | The sandbox is briefly unreachable, or a transfer limit was reached. |

Unknown fields are refused, never ignored.

The control plane limits each API key to 20 requests per second. A refused request carries the `ratelimit-limit`, `ratelimit-remaining`, and `ratelimit-reset` headers and no `Retry-After`.

## Control Plane Forwarding

| Status | Cause |
| - | - |
| 404 | The sandbox or template ID names a region that does not exist. |
| 404 | `region` on a create, or `?region=` on a list, names a region that does not exist. The body carries code `10005` and the title `Sandbox region not found`. |
| 502 | The data plane of the sandbox's region did not answer. The control plane does not retry. |
