# Errors

The errors a sandbox call answers with, what each means, and what to do next.

| Answer | Meaning | What to do |
| --- | --- | --- |
| `401 unauthorized` | API key missing or wrong. | Ask for a working API key. |
| `401 key_expired` | The key's last day has passed. | Ask for a new key. |
| `403 key_address_forbidden` | The key may not be used from the address the request came from. `message` names it. | Do not retry. Tell the person the address. |
| `403 key_action_forbidden` | The key was not made with the action this call takes. `message` names it. | Do not retry. Ask for a key that may, or do without. |
| `403 key_exceeds_caller` | A key was asked to make a key stronger than itself. | Ask for less: fewer actions, sandboxes, days or addresses. |
| `400 template_required` | A key limited to several templates made a sandbox without naming one. | Send `templateId`, one of the key's. |
| `400 invalid_request` | A field is missing or malformed. | Read `message`, fix, resend. |
| `400 idempotency_key_required` | A create came without its key. | Add `Idempotency-Key`. |
| `400 ttl_too_long` | Time limit above the ceiling. | Ask for less. |
| `400 confirm_delete_required` | Delete without its confirm header. | Add it only if you mean it. |
| `400 invalid_path` | A file path that is absolute or leaves the work folder. | Send a relative path. |
| `400 invalid_host` | A host for a kept-out variable that cannot be one, or none, or more than 10. | Read `message`, fix it, resend. |
| `400 invalid_network_policy` | An outbound rule or an address that cannot be one. | Read `message`, fix it, resend. |
| `400 rule_on_template` | `outbound` sent to a sandbox. | Set the rule on its template: `PUT /v1/templates/{id}/network`. |
| `402 billing_required` `out_of_credit` | The account's plan or balance does not allow it. | Tell the person. `message` says what would change it. |
| `402 size_not_on_plan` | The plan does not make sandboxes of that size. | Pick a size the plan makes, or tell the person: `message` names the plan that does. |
| `403 recipient_not_allowed` | A message for an address other than the account's own, or one never proved to be its owner's. | Leave `to` out. Do not try another address. |
| `403 mail_suspended` | Mail was switched off for the account by whoever runs the service. | Do not retry. Tell the person. |
| `404 not_found` | No sandbox of yours has that id. | List your sandboxes. |
| `404 file_not_found` | The file does not exist. | Check the path. |
| `409 sandbox_not_running` | The sandbox is stopped. | Start it, then repeat. |
| `409 sandbox_archived` | Stopped, disk in storage. | Start, poll until running, repeat. |
| `409 sandbox_migrating` | Moving to another server. | Poll every 10 seconds, then repeat. |
| `409 invalid_state` | Not possible from its current status. | `GET` it, wait for running or stopped. |
| `409 account_limit_reached` | Account holds its maximum. | Reuse one. Delete only if agreed. |
| `409 capacity_exceeded` | No room right now in the region. | Another region from `error.regionsWithRoom`, with a new key, or wait a minute. |
| `409 name_taken` | A sandbox has that name. | It may be yours: list and reuse. |
| `409 idempotency_conflict` | Key used with a different body. | New sandbox, new key. |
| `409 snapshot_limit_reached` | Account keeps its maximum of snapshots. | Delete one you no longer need. |
| `409 template_in_use` | Sandboxes are on that template. | Put them on another template first. |
| `409 default_template` | `default` is not deleted or renamed. | Leave it. |
| `409 not_on_template` | `apply` named a sandbox not on that template. | Name only sandboxes on it. |
| `409 not_hidden` | New hosts for a plain variable. | Set it with its value and `hosts`. |
| `409 hosts_widened` | A host a kept-out variable is not sent to now, without its value. | Set it again with its value and `hosts`. |
| `409 too_many_addresses` | A template's addresses and a sandbox's own over 100. | Take some off, or use a range. |
| `409 restore_blocked` | A sandbox made from this one after the snapshot still exists. | Delete that one, or leave this as it is. |
| `409 route_limit_reached` | Already 5 ports registered. | Reuse a port. |
| `409 ssh_unavailable` | SSH could not be set up in the machine, or no port could be opened. | Read `message`. Do not retry at once. |
| `409 desktop_unavailable` | The machine has no desktop, or it did not start. | Read `message`. A new sandbox has one. |
| `409 desktop_not_running` | The desktop is off, or not up yet. | Turn it on, then repeat. |
| `409 browser_unavailable` | The machine cannot run its browser to be driven from outside, or Chrome did not start. | Read `message`. A new sandbox can. |
| `409 mail_off` | Mail is off for the sandbox, so it can send none. | Turn it on, then repeat. |
| `409 recipient_refuses_mail` | The address refused a message for good. | Nothing is sent to it for a day. Do not retry. |
| `413 message_too_large` | A message over 10 MB as it is transmitted. | Send less, or leave an attachment out. |
| `422 create_failed` | Create failed for good. | New key, try once more. |
| `429 running_limit_reached` | The account runs as many sandboxes as its plan allows. | Stop or delete one you no longer need, or tell the person. |
| `429 burst_fee_too_high` | The start would cost more in burst fees than `Agental-Max-Burst-Fee` allows. | Wait `retryAfterSeconds`, or allow the fee in `feeMicros`. |
| `429 burst_budget_reached` | This month's burst fees would pass the account's budget. | Wait `retryAfterSeconds`, or tell the person. |
| `429 mail_limit_reached` | The account has sent what it may in an hour or a day, or its stored mail is full. | Read `message`. Wait, or delete mail. |
| `500 host_error` `internal_error` | The machine, its host or agental failed. | Retry once after 10 seconds, then report. |
| `501 driver_operation_unavailable` | This deployment cannot do that. | Do not retry. |
| `501 hidden_variables_unavailable` | A variable cannot be kept out of the sandbox here. `GET /v1/policy` says so as `hiddenVariables`. | Do not retry. Tell the person. |
| `503 sandbox_moved` | Moved to another server mid-request. | Send the request again. |
| `503 metrics_unreadable` | Not one server answered for its readings. | Ask again in a minute. |
| `503` to a WebSocket | A WebSocket to a public address opened as agental restarted. Nothing reached the sandbox. | Open it again after a second. |
| `503 uncertain_operation` | Outcome not known yet. | Wait 10 seconds, `GET`, go by status. |
| `502` `504` `52x` | A proxy answered. | Wait 10 seconds. Retry a create with the same key. |

---

Every page of these docs as Markdown: [llms.txt](https://agental.io/llms.txt)