Errors

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

For your agent

agental.io/docs/errors.md

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.

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]