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

# Error Codes

> Look up an API error code to see its HTTP status, whether your work started, whether to retry, and what to do next.

This reference lists every code BoxRouter returns and the guides print.
Handle a code you do not know by its HTTP status: new codes can be added.
To decide what to do after a failed request, start with [Recover from Errors](https://boxrouter.ai/docs/errors.md).

## Read the Columns

Branch on `error.code`, `error.outcome` and `error.retry`, never on `error.message`. The Outcome column is the usual value; the response field is exact. The Retry column is the `retry` field: `safe`, `after_fix`, `check_outcome` or `never`.

| Outcome | Meaning |
| - | - |
| Not started | The field is `not_started`: BoxRouter reports that the work did not begin. |
| Maybe started | The field is `unknown`: the work may exist, so check the operation or resource before you repeat it. |
| Started | The field is `completed` or `partial`: the work happened. Read the resource instead of repeating it. |

| Retry | Meaning |
| - | - |
| Yes | Resend the same request. |
| After a fix | Change the request or your setup first, then resend. |
| Check first | Check `outcome` and the resource before you resend. |
| No | Do not resend. The entry says what to do instead. |

## Codes

| Code | Status | Outcome | Retry | What to Do |
| - | - | - | - | - |
| `account_exists` | 409 | Not started | After a fix | A sign-in with a verified email address was refused because an account with that address uses a different sign-in method. Sign in with the method named in `details.sign_in_method`. `details.masked_email` shows which account it is. |
| `account_unhealthy` | 402 | Not started | After a fix | The provider refused to create the sandbox because your connected account there needs credits or billing set up. Resolve the credit or payment requirement with the provider, then reconnect the account. See [provider keys](https://boxrouter.ai/docs/provider-keys.md). |
| `actions_authority_changed` | 409 | Not started | After a fix | The job's binding, policy, funding or connected accounts changed before its sandbox was created. Run the job again once its claim and Actions settings are current. |
| `actions_candidate_ceiling_withdrawn` | 409 | Not started | After a fix | A route in the job's admitted set was withdrawn. Admit the job again; a changed ceiling is never widened. |
| `actions_candidate_outside_ceiling` | 409 | Not started | After a fix | The next route is outside the job's admitted set. Admit the job again; a changed ceiling is never widened. |
| `actions_candidate_record_invalid` | 409 | Not started | After a fix | The job's stored candidate record cannot be read, so BoxRouter did not create from it. Admit the job again; a changed format, ceiling or record is never widened. |
| `actions_create_budget_exhausted` | 409 | Not started | After a fix | The job's create time ran out before this attempt. Admit the job again; a changed format, ceiling or record is never widened. |
| `actions_create_format_mismatch` | 409 | Not started | After a fix | The job's stored candidate set and this grant are different formats. Admit the job again; a changed format, ceiling or record is never widened. |
| `actions_sandbox_protected` | 403 | Not started | No | A GitHub Actions sandbox may hold job secrets, so access stays blocked, including after the job ends. Read the job's logs and artifacts in GitHub, or cancel the job there. |
| `agent_not_found` | 404 | Not started | After a fix | No launch agent has the name you sent. Use an agent name returned by `GET /api/v1/agents`, or send an inline manifest. See [manifest](https://boxrouter.ai/docs/launch/manifest.md). |
| `already_refunded` | 409 | Not started | No | The credit purchase has already been refunded, so no credit is left to refund. Nothing to do. Read the purchase to see the completed refund. See [credits](https://boxrouter.ai/docs/credits.md). |
| `authorization_error` | 403 | Maybe started | Check first | The provider denied access, including while BoxRouter was observing a command. Check `outcome` and effects before repeating work. Check provider account access or the sandbox user's path permissions. |
| `candidate_admission_unavailable` | 503 | Not started | No | BoxRouter cannot admit this create right now because of a problem on its side. Nothing started. Contact support with the `request_id`. |
| `capability_unavailable` | 409, 503 | Maybe started | Check first | A needed capability is unavailable, or BoxRouter Volumes are not enabled or their usage cannot be read. Follow `fix`; if work may have started, inspect the operation first. See [inspect an uncertain operation](https://boxrouter.ai/docs/errors.md#inspect-an-uncertain-operation). |
| `capability_unverified` | 409 | Not started | After a fix | The selected route has not verified the capability the operation needs. Create the sandbox with a route that has verified this capability. |
| `card_setup_rate_limit` | 429 | Not started | Yes | Too many card setup attempts were started in the last hour. Add the card again after the `Retry-After` time, or pay with Stripe Checkout, which does not save the payment method. See [credits](https://boxrouter.ai/docs/credits.md). |
| `code_ref_not_found` | 404 | Not started | After a fix | The branch, tag or commit you named in `code` does not exist in the repository. Choose an existing branch, tag or full commit SHA, then resend. See [private repositories](https://boxrouter.ai/docs/launch/private-repositories.md). |
| `code_reference_moved` | 409 | Not started | After a fix | The run's pinned commit is no longer the one resolved for it. Create a new run to pick up the repository's current commit. |
| `code_repository_not_authorized` | 403 | Not started | After a fix | The repository is linked to your workspace, but the BoxRouter GitHub App can no longer read it. Give the App access to the repository on GitHub, then resend. See [private repositories](https://boxrouter.ai/docs/launch/private-repositories.md). |
| `code_repository_not_found` | 404 | Not started | After a fix | GitHub has no repository at the `code` URL, or BoxRouter could not read it. Nothing was started. Check the owner and name, connect GitHub access for a private repository, then resend. See [private repositories](https://boxrouter.ai/docs/launch/private-repositories.md). |
| `code_repository_not_private` | 400 | Not started | After a fix | The bound GitHub repository is no longer private. Retry using the public repository path. |
| `code_repository_not_public` | 404 | Not started | After a fix | The repository is private and is not linked to this workspace. Follow `fix` to link the repository, then send the request again. |
| `code_repository_resolution_failed` | 502 | Not started | Yes | GitHub could not verify this workspace's repository access. Send the same request again after the GitHub connection recovers. |
| `command_failed` | 409 | Started | After a fix | The command exited unsuccessfully. Read the command's output and fix the cause. See [commands](https://boxrouter.ai/docs/commands.md). |
| `command_observation_busy` | 409 | Not started | Yes | A sandbox cannot be deleted while a command's output is still being observed. Nothing was started. The SDKs and CLI resend the delete after the `Retry-After` wait; over HTTP, you wait and send it again. |
| `conflict` | 409 | Maybe started | Check first | The request conflicts with existing state: a recorded operation or a running command. Check `outcome` and state; wait for a running command. `details.sandbox_ids` lists blocking sandboxes. See [inspect an uncertain operation](https://boxrouter.ai/docs/errors.md#inspect-an-uncertain-operation). |
| `contract_violation` | 409 | Maybe started | Check first | The request or a provider response did not match the expected contract. A process may have started if `outcome` is `partial` or `unknown`. Check the sandbox and effects before retrying; follow `fix`. |
| `credentials_rejected` | 409, 422 | Not started | After a fix | The provider rejected the key you pasted (422), or the saved key when you created a sandbox (409). Check the key, paste a new one under **Provider Keys**, or name another provider. See [provider keys](https://boxrouter.ai/docs/provider-keys.md). |
| `database_unavailable` | 503 | Maybe started | Check first | BoxRouter's database is unavailable, so the request could not finish. A write may have run. Check the operation or resource before retrying a write. Retry reads after a minute. See [inspect an uncertain operation](https://boxrouter.ai/docs/errors.md#inspect-an-uncertain-operation). |
| `dispatch_limit_reached` | 409 | Not started | After a fix | This copy reached its limit of provider calls. Raise the run's call limit, or start a new run. |
| `dispute_open` | 409 | Not started | After a fix | The payment has an open dispute, so it cannot be refunded. Wait for the dispute to be resolved, or contact support. |
| `dockerfile_context_unsupported` | 400 | Not started | After a fix | The providers you named cannot build this repository's Dockerfile. Remove `placement.preferences.only`, or prepare the image first with `images.prepare`. |
| `expired` | 410 | Not started | Check first | The terminal, process output, command output or file you asked for has expired and cannot be replayed. Check whether the output remains, reconnect a terminal if needed, and check effects before repeating. See [processes](https://boxrouter.ai/docs/processes.md). |
| `forbidden` | 403 | Not started | After a fix | The key or signed-in person lacks permission, or an access check refused the request. Read the message and `fix`, if present. Check key permissions or ask a workspace administrator for access. |
| `fraud_review` | 409 | Not started | Yes | The payment is under fraud review and cannot be refunded yet. Try again after the review finishes, or contact support. |
| `gate_unavailable` | 409 | Not started | After a fix | The account no longer has a capability that this sandbox was created with. Reconnect an account that has the capability, or create the next sandbox elsewhere. |
| `idempotency_key_reused` | 409, 422 | Not started | After a fix | The `Idempotency-Key` was already used for a different request (409 on settings changes, 422 on credit refunds). Send a new key for a new request. Reuse a key only with an identical request. |
| `identity_unavailable` | 503 | Not started | Yes | Email sign-in is temporarily unavailable. Wait a moment, then try signing in again. |
| `image_architecture_unsupported` | 400 | Not started | After a fix | The image has no version for the chips providers use. Choose an image with a `linux/amd64` version. |
| `image_digest_resolution_failed` | 400 | Not started | After a fix | BoxRouter could not resolve the public image reference. Use an immutable image reference with a `sha256` digest. |
| `image_preparation_unsupported` | 400 | Not started | After a fix | The chosen provider cannot prepare this kind of image source. Choose a provider that prepares this image source. |
| `image_setup_timeout` | 504 | Not started | After a fix | Preparing the standard image in your provider account took longer than the request allowed. Retry shortly with a new `Idempotency-Key`; it uses the image once preparation finishes. |
| `image_tag_unresolved` | 400 | Not started | After a fix | A private image tag cannot be resolved without registry credentials. Follow `fix`: reference the image by digest, then send the request again. |
| `inline_secret_values_refused` | 422 | Not started | After a fix | A run cannot carry secret values in its request. No run was created. Save the secret first, then list its name in the manifest `secrets`. |
| `insufficient_credit` | 402 | Not started | After a fix | Your available credit is below the amount BoxRouter must reserve before work starts. `details` has `required_nanodollars` and `available_nanodollars`. Buy credits under **Credits**, or ask for a shorter `lifetime_seconds` or a smaller sandbox. See [credits](https://boxrouter.ai/docs/credits.md). |
| `internal_error` | 500 | Maybe started | No | BoxRouter hit an unexpected fault on its side and could not complete the request. Read the operation (`GET /operations/{operation_id}`) before sending again. If it continues, contact support with the `request_id`. |
| `invalid_manifest_encoding` | 400 | Not started | After a fix | The repository manifest is not UTF-8 text. Save the manifest as UTF-8 text and send the request again. |
| `invalid_observer_hop` | 403 | Not started | After a fix | The request to read output came through a route that may not relay it. Send the request directly to BoxRouter, not through another service. |
| `invalid_request` | 400, 413, 422, 428 | Not started | After a fix | The request is malformed (400, 422), too large (413), or lacks a required `If-Match` header (428). Follow `fix`: correct the request, send a smaller body, or send the settings' `ETag` in `If-Match`. See [api overview](https://boxrouter.ai/docs/api-overview.md). |
| `invalid_run_spec` | 400 | Not started | After a fix | The run's stored specification cannot be launched. Create a new run with a valid agent manifest. |
| `invalid_source_manifest` | 400 | Not started | After a fix | The repository manifest is not valid YAML or not a YAML object. Correct the manifest file named in `details.path`, then send the request again. |
| `invalid_state` | 409 | Maybe started | Check first | The resource is not in the required state, or a path has an incompatible type or contents. Check `outcome` and the resource before repeating a change, then fix the path or wait. |
| `job_claim_lost` | 409 | Not started | After a fix | This job no longer holds the claim or authority to create. Run the job again once its claim and Actions settings are current. |
| `knob_not_named` | 400 | Not started | After a fix | A requirement needs a setting the request did not name, such as `tcp_ports.tls`. Follow `fix`: name the setting, then send the request again. |
| `launch_failed` | 409 | Maybe started | Check first | Launch preparation failed. A sandbox may have been created, and its cleanup may not be confirmed. Read `details` and follow `fix`. Check sandbox cleanup and any external effects of preparation before retrying. See [manifest](https://boxrouter.ai/docs/launch/manifest.md). |
| `launch_incomplete` | 409 | Maybe started | Check first | The previous launch has no saved preparation result, so BoxRouter cannot replay it safely. Read the sandbox in `details.sandbox_id`, then follow `fix`. |
| `launch_run_position_conflict` | 409 | Not started | After a fix | This run index is already used by a different launch. Use a new `run.index` or `run.id`. |
| `lifetime_cap_exceeded` | 400 | Not started | After a fix | `lifetime_seconds` is longer than the fitting accounts allow, or not a length they support. Follow `fix`: ask for less, within `details.maximum_seconds`, or connect an account that allows longer. |
| `lifetime_funding_conflict` | 409 | Not started | After a fix | The records that fund this lifetime extension disagree, so BoxRouter did not extend the sandbox. `details.reason` names the check. Read the sandbox for its current lifetime. If it repeats, contact support with the `request_id`. |
| `lifetime_limit` | 409 | Maybe started | Check first | The requested lifetime exceeds a limit or is already used up. Check `outcome` and the sandbox's lifetime before extending again. Follow `fix`; choose a shorter lifetime or another route if needed. See [lifecycle](https://boxrouter.ai/docs/lifecycle.md). |
| `lifetime_used_up` | 409 | Not started | After a fix | The sandbox has no running time left, so it cannot resume as it is. Create a sandbox with a longer `lifetime_seconds`, or request `resources.extendable_lifetime` and extend it while running. See [pause resume](https://boxrouter.ai/docs/pause-resume.md). |
| `managed_funding_unavailable` | 503 | Not started | Yes | BoxRouter cannot fund a managed lifetime extension right now. Retry in a few minutes, create a new sandbox with the lifetime you need, or use your own provider account. |
| `method_not_allowed` | 405 | Not started | After a fix | The HTTP method is not allowed for this path. Use one of the methods listed in the `Allow` response header. |
| `no_eligible_route` | 409 | Not started | After a fix | No connected provider fits the request. A workspace with no provider keys and no credits gets this too. Read `fix`, `details.excluded` and `details.nearest`. Connect an eligible provider, buy credits, or change the request. See [routing](https://boxrouter.ai/docs/routing.md). |
| `not_found` | 404 | Maybe started | Check first | The resource, path, route or credit operation was not found, or is in another workspace. Check `outcome` and the resource before repeating a change. Check the ID or path; API paths start with `/api/v1`. |
| `not_named` | 409 | Not started | After a fix | The call uses a capability the sandbox's creation request did not name, or more of it than the request named. Create the next sandbox with the capability named. `details.requirements` gives the corrected line to send. |
| `not_running` | 409 | Not started | After a fix | The call needs a running sandbox, but it is paused or stopped. Resume it with `POST /sandboxes/{id}/resume`, check `cold_restart`, then send the call again. See [pause resume](https://boxrouter.ai/docs/pause-resume.md). |
| `nothing_to_refund` | 409 | Not started | No | There is no unused credit to refund on this purchase. Nothing to do. Read the purchase to see what is left. See [credits](https://boxrouter.ai/docs/credits.md). |
| `output_limit` | 413 | Maybe started | Check first | The output is larger than one response can carry, such as a file over `limits.file_transfer_bytes`. Check `outcome` and command effects before retrying. Use a Volume for a file larger than `limits.file_transfer_bytes`. See [options](https://boxrouter.ai/docs/commands.md#options). |
| `overloaded` | 503 | Not started | Yes | This server has reached its capacity for terminals, commands, native streams, or volume transfers. Retry after the `Retry-After` interval, or close a terminal or finish a command you no longer need. |
| `payment_declined` | 402 | Not started | After a fix | The saved card was declined for a credit purchase. Use a different card or pay with Stripe Checkout. `details.failure_reason` gives the short reason. See [credits](https://boxrouter.ai/docs/credits.md). |
| `payment_method_required` | 409 | Not started | After a fix | Auto top-up needs a default saved card. Save a card, make it the default, then enable auto top-up again. See [credits](https://boxrouter.ai/docs/credits.md). |
| `payment_provider_rejected` | 502 | Maybe started | Check first | Stripe rejected the request. A billing details update may be unconfirmed. Check `outcome` and read the current billing details or purchase before correcting or repeating the request. |
| `payment_provider_unavailable` | 503 | Maybe started | Check first | The payment provider gave no usable answer, so the outcome may be unknown. For a credit purchase, resend the same request with the same `Idempotency-Key`; for other calls, check the outcome first. |
| `payments_unavailable` | 503 | Not started | Yes | Credit purchases are not available on this deployment right now. Try again later. |
| `policy_denied` | 409 | Not started | After a fix | BoxRouter's managed-route policy does not allow the next route for this workspace. Choose an enabled managed provider, or connect your own provider account. |
| `port_not_listening` | 409 | Not started | After a fix | The process exited before its `wait_for_port` accepted connections, or the port stayed closed for 30 seconds. The process was ended. Read `details.stdout_tail` and `details.stderr_tail`, fix the listener, then start again. See [connect](https://boxrouter.ai/docs/connect.md). |
| `preview_access_refused` | 502 | Maybe started | No | A preview was opened with other access than you asked for, so it was not returned. Check `details.revoked`; if the preview could not be ended, destroy the sandbox to close `details.port`. |
| `price_unknown` | 409 | Not started | After a fix | A managed route has no confirmed price or size for this request. Choose a route with a known size and price, or connect your own provider account. |
| `privacy_admission_unavailable` | 400 | Not started | After a fix | Privacy cannot be enforced on this creation path. Follow `fix`: use a creation service with privacy admission enabled. |
| `privacy_persistence_conflict` | 409 | Not started | After a fix | The request needs stored content, such as a volume, but `boxrouter_content_retention` is `transient`. Remove `transient` from the request, API key or workspace, or send a request that stores nothing. |
| `private_image_managed_route_unavailable` | 400 | Not started | After a fix | Private images run only on your own provider keys for now. Connect your own provider key and create the private image there. |
| `process_observer_lost` | 410 | Maybe started | Check first | The connection reading this process's output stopped, so its output and input are unavailable. The process may still run. Read the process state or cancel it. Check its effects before starting another command. See [processes](https://boxrouter.ai/docs/processes.md). |
| `promotion_already_redeemed` | 409 | Not started | No | This promo code was already redeemed on the date in the message. It did not grant credit again. Nothing to do. `details.redemption` shows the earlier redemption. |
| `promotion_code_invalid` | 404 | Not started | After a fix | The promo code is not valid. Check the code and enter it again. |
| `provider_budget_exhausted` | 409 | Not started | No | This run's provider budget allows no further sandbox create on this route. Stop. The operator who set the budget must allow more; resending does not help. |
| `provider_error` | 502 | Maybe started | Check first | The provider could not be reached, failed the operation, or rejected the account's credentials. Check `outcome`, then inspect the operation or sandbox before retrying or choosing another provider. See [inspect an uncertain operation](https://boxrouter.ai/docs/errors.md#inspect-an-uncertain-operation). |
| `provider_not_enabled` | 409 | Not started | After a fix | The provider you chose is not enabled on this deployment. Choose a provider this deployment has enabled. See [provider support](https://boxrouter.ai/docs/provider-support.md). |
| `provider_policy_unknown` | 409 | Not started | After a fix | Privacy evidence for this sandbox cannot be verified, so BoxRouter did not start the operation. Use a sandbox with verifiable privacy admission. |
| `provider_quota` | 429 | Not started | After a fix | Your provider account is over its plan or quota limit. `native_message` has the provider's words. Free capacity or raise the limit there. BoxRouter's own limit is `rate_limited`. See [limits your provider account sets](https://boxrouter.ai/docs/limits.md#limits-your-provider-account-sets). |
| `purchase_in_progress` | 409 | Not started | Yes | A credit purchase is still in progress, so it cannot be refunded or repeated yet. Wait for the purchase to finish, then try again. |
| `quota_exceeded` | 429 | Not started | Yes | BoxRouter's capacity for this route is full right now. Wait a few minutes and send the same request again, or connect your own provider account. |
| `quote_changed` | 409 | Not started | After a fix | The purchase total changed since you requested the quote. Review the current quote in `details.quote` and confirm it. |
| `rate_limited` | 429 | Not started | Yes | A rate limit was hit: request capacity, repeated failed authentication, a provider's request rate, or feedback volume. Wait for `Retry-After`, then send the same request again. See [limits](https://boxrouter.ai/docs/limits.md). |
| `recovery_sandbox_mismatch` | 409 | Started | Check first | The replayed create returned a different sandbox than the one recorded. Check the run's sandboxes; BoxRouter removes unowned copies. |
| `refund_amount_changed` | 409 | Not started | After a fix | The refundable amount changed since the preview you reviewed. Review the current preview in `details.preview` and confirm it. |
| `refund_below_minimum` | 409 | Not started | No | The refundable amount is below the minimum refund. Nothing to do. The remaining credit is too small to refund. |
| `refund_daily_limit` | 429 | Not started | Yes | The workspace has reached its refund limit for the day. Try again the next day, or contact support. |
| `refund_fee_unavailable` | 409 | Not started | Yes | The payment's processing fee is not available yet, so the refund cannot be computed. Try again shortly. |
| `refund_in_progress` | 409 | Not started | Yes | A refund for this purchase is already in progress. Wait for it to finish, then read the purchase. |
| `refund_rate_limit` | 429 | Not started | Yes | Too many refund requests were sent in a short time. Wait for `Retry-After` (60 seconds by default), then try again. |
| `refund_retry_requires_support` | 409 | Not started | No | A refund that failed earlier cannot be retried automatically. Contact support to retry this refund. |
| `refund_window_closed` | 409 | Not started | No | The refund window, 24 hours after purchase, has closed. Nothing to do. This purchase can no longer be refunded. |
| `repository_file_unsupported` | 400 | Not started | After a fix | The repository has a link or special file, and BoxRouter builds a Dockerfile from regular files only. Replace it with a regular file, then send the request again. |
| `repository_too_large` | 400 | Not started | After a fix | The repository is too large to use as a Dockerfile build context. Reduce the repository, or prepare the image first with `images.prepare`. |
| `request_timeout` | 408 | Not started | Yes | The request body, or a terminal wait, did not complete in time. Send the whole request body promptly, then try again. |
| `reserved_env_refused` | 400, 422 | Not started | After a fix | A run cannot set the variables BoxRouter provides to each copy. Remove the names in `details.names` from the environment and secret names. |
| `resource_limit` | 413, 507 | Maybe started | Check first | A limit was exceeded: file size, volume storage, volume count, or 10,000 directory entries. Follow `fix`. Use a Volume for a large file; before retrying a volume save, inspect its head checkpoint. See [limits](https://boxrouter.ai/docs/limits.md). |
| `routing_overrides_forbidden` | 400 | Not started | After a fix | The workspace's routing settings prevent per-request preference overrides, and the request set `preferences.order`, `sort` or `allow_fallbacks`. Remove those preferences from the request. See [routing settings](https://boxrouter.ai/docs/routing-settings.md). |
| `routing_settings_stale` | 412 | Not started | After a fix | The routing settings section changed after you loaded it, so your edit was not applied. Read the section again, apply your edit, and send it with the new ETag. See [routing settings](https://boxrouter.ai/docs/routing-settings.md). |
| `run_limit_exceeded` | 429 | Not started | After a fix | The request asked for more copies than one run may start. `details.limit` shows the maximum. Nothing was started. Use `details.limit` copies or fewer, or split the work across runs. See [copies](https://boxrouter.ai/docs/launch/copies.md). |
| `sandbox_ended` | 410 | Maybe started | Check first | The sandbox ended. A command sent afterward did not start (`not_started`); one running as it ended is `unknown`. Check an unknown command's effects, then create a sandbox with a longer `lifetime_seconds`. See [lifecycle](https://boxrouter.ai/docs/lifecycle.md). |
| `secret_missing` | 400 | Not started | After a fix | The launch manifest names secrets that are not supplied or stored in the workspace. Supply the secrets in `details.names`, or add them under **Secrets** or with `boxrouter secrets set NAME`. See [manifest](https://boxrouter.ai/docs/launch/manifest.md). |
| `secrets_unavailable` | 503 | Not started | No | BoxRouter cannot store this secret or environment right now because of a problem on its side. Nothing started. Contact support with the `request_id`. |
| `session_required` | 403 | Not started | No | This operation needs a signed-in workspace session, not an API key. Previewing or requesting a refund is one. Sign in to the dashboard and do it there. |
| `source_file_not_found` | 400 | Not started | After a fix | The manifest file is not in the repository at the selected commit. Add `boxrouter.yaml` at that commit, or pass the file's path after a colon. See [your own agent](https://boxrouter.ai/docs/launch/your-own-agent.md). |
| `source_file_too_large` | 413 | Not started | After a fix | The repository manifest file exceeds the 64 KiB limit. Keep the manifest at or below 64 KiB, then send the request again. |
| `source_rate_limited` | 503 | Not started | Yes | GitHub's rate limit stopped BoxRouter from resolving the repository. Wait until `details.retry_after_seconds` passes, then send the same request again. |
| `source_ref_not_found` | 400 | Not started | After a fix | The source repository reference was not found. Choose an existing branch, tag or full commit SHA, then send the request again. |
| `source_repository_not_accessible` | 404 | Not started | After a fix | BoxRouter could not read the repository named by `source`. Nothing was started. Check the repository in `source` and connect GitHub access if it is private, then send the request again. See [private repositories](https://boxrouter.ai/docs/launch/private-repositories.md). |
| `source_repository_not_found` | 400 | Not started | After a fix | The source repository was not found. Check the repository name, then send the request again. |
| `source_repository_not_private` | 400 | Not started | After a fix | The bound GitHub repository is not private. Retry using the public repository path. |
| `source_repository_not_public` | 400 | Not started | After a fix | The repository is not public, so it cannot be read without a token. Follow `fix`: link the repository to the workspace or make it public. |
| `source_resolution_failed` | 502 | Not started | Yes | BoxRouter could not resolve the source repository through the GitHub API. Send the same request again after GitHub recovers. |
| `source_resolution_timeout` | 504 | Not started | Yes | The GitHub API request timed out. Send the same request again after the connection recovers. |
| `spend_limit_exceeded` | 402 | Not started | After a fix | The workspace spend limit you set would be exceeded by this managed sandbox; `details` names the period and amounts. Raise the workspace spend limit, or wait for the period to reset. See [spend limits](https://boxrouter.ai/docs/spend-limits.md). |
| `terminal_closed` | 410 | Not started | After a fix | The terminal has exited, so it takes no more input. Open a new terminal to continue. See [connect](https://boxrouter.ai/docs/connect.md). |
| `terminal_observer_lost` | 410 | Maybe started | After a fix | The connection observing this terminal was lost, so the terminal cannot resume from that connection. Open a new terminal connection to continue. |
| `timeout` | 504 | Maybe started | Check first | BoxRouter lost the answer, so the call may have run. A command that reached its `timeout_seconds` is a result. Read the operation, or resend a create with its `Idempotency-Key`. See [inspect an uncertain operation](https://boxrouter.ai/docs/errors.md#inspect-an-uncertain-operation). |
| `unauthenticated` | 401 | Not started | After a fix | No credential was sent, or the credential is invalid, revoked, or expired. A valid API key also gets this on dashboard-only operations, such as creating keys. Set a valid `BOXROUTER_API_KEY` or sign in. |
| `unavailable` | 503 | Not started | Yes | A feedback submission or GitHub webhook could not be handled because the service behind it is temporarily unavailable. Try again later, or email [support@boxrouter.ai](mailto:support@boxrouter.ai) for feedback. |
| `unrecognised_word` | 400 | Not started | After a fix | A name in the request, such as a provider in `preferences.only`, is not one BoxRouter knows. Nothing started. Use a name from `details.known`, or remove the field. |
| `unsupported_feature` | 422 | Not started | After a fix | The sandbox's provider or account does not support this operation or launch feature. Check the sandbox's provider in `route.provider`, or create the sandbox on a provider that supports the operation. See [provider support](https://boxrouter.ai/docs/provider-support.md). |
| `volume_busy` | 409 | Not started | After a fix | A writer is running or still releasing the volume, an upload or save is open, or too many requests wait on a release. Destroy details.writer\_sandbox\_id, or wait a few seconds and retry. See [volumes](https://boxrouter.ai/docs/volumes.md). |
| `volume_incompatible` | 409 | Not started | After a fix | The volume version does not match the requested image or architecture. Create the sandbox with the image and architecture the version was saved with, named in `fix`. See [volumes](https://boxrouter.ai/docs/volumes.md). |
| `volume_lease_lost` | 409 | Maybe started | After a fix | The volume's writer lease was lost, so this sandbox can no longer save to it. Create a new writer sandbox before saving again. See [volumes](https://boxrouter.ai/docs/volumes.md). |
| `volume_not_attached` | 409 | Not started | After a fix | The sandbox is not attached as this volume's writer. Create a sandbox with the volume as `{id, access: write}` first. See [volumes](https://boxrouter.ai/docs/volumes.md). |
| `volume_restore_failed` | 502 | Started | Check first | Restoring the volume version failed after the provider had acted, so `outcome` is `partial`. `operation_id` names the operation. Check `outcome` and the operation, then follow `fix` before creating or resuming again. See [volumes](https://boxrouter.ai/docs/volumes.md). |
| `volume_save_failed` | 409, 502 | Maybe started | Check first | Saving the volume failed (502 on a requested save, 409 on a save before destroy or an automatic save). Follow `fix`. If the save may have started, inspect the head checkpoint first. See [volumes](https://boxrouter.ai/docs/volumes.md). |
| `volume_unavailable` | 409 | Not started | After a fix | No available route can mount this volume, or safe volume mounts are unavailable. Choose an eligible provider, or create the sandbox without a volume until mounts are available. See [volumes](https://boxrouter.ai/docs/volumes.md). |
| `wrong_region` | 421 | Not started | After a fix | The organization is served from another region. Send the request to the organization's home region, named in `details.home_region`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.