> ## 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.

# List the Providers That Run Actions

> Public: needs no key or session. Lists each listed provider that runs Actions runners, how a
new workspace pays for it (`supply`) and the runner image profiles it serves (`profiles`).
A provider that is not publicly listed is left out. A workspace's own readiness
(`getActionsReadiness`) is still the answer for what it can run now. Not paginated; the
response may be cached for a minute.




## OpenAPI

````yaml openapi.json GET /actions/providers
openapi: 3.1.1
info:
  title: BoxRouter API
  version: 0.10.351
  description: >
    Hosted sandbox control using a BoxRouter API key. Provider credentials are

    configured separately and never included in workload requests. Same-origin
    browser

    sessions are also accepted. Browser mutations require the configured Origin
    and

    the session-bound X-CSRF-Token; after an organization switch, every
    cookie-authenticated

    mutation must also send X-BoxRouter-Selection-Version with the version read
    from /auth/me.

    A stale version returns 409 organization_changed before side effects; its
    details contain

    the current selection_version. Bearer keys do not require browser CSRF or
    selection headers. Core adapters

    execute on BoxRouter servers.

    Sandbox IDs are BoxRouter resource IDs; every access is scoped to the
    caller's

    workspace. Routing occurs only at creation. Subsequent operations retain the

    original provider, upstream account and billing mode.

    Mutation endpoints accept an Idempotency-Key. Clients should generate one
    per

    logical mutation and retain it for reconciliation. The server records
    workspace,

    method, path and request identity before dispatch. Buffered requests include
    the full

    body hash. Streaming uploads reserve the key first, lock concurrent
    dispatch, and

    finalize the body hash as bytes arrive; interrupted uploads remain
    unresolved and

    must not be redispatched. A replay must validate the complete body before
    returning

    a recorded success. Reusing a key with different input

    returns 409; identical input returns the recorded result or an
    unresolved-operation

    error without dispatching again. Records with unknown outcomes are retained
    until

    resolved; completed records remain available for at least 24 hours. This
    does not

    promise exactly-once upstream execution or authorize automatic mutation
    retries.


    ## Guarantees


    Each operation's description states what you can rely on, what you can set
    and what is not promised. These rules apply to all operations:


    - File operations may act with more authority than the command user: do not
    rely on file permissions to keep the file API out. Commands run as the
    command user.

    - Some features need capabilities. A request that names them runs only on
    infrastructure that supports them, and an operation the sandbox was not
    created for returns a clear error; behaviour never changes silently.
servers:
  - url: https://api.boxrouter.ai/api/v1
security:
  - BoxRouterKey: []
  - BrowserSession: []
tags:
  - name: agents
    description: Discover launch manifests available to this workspace.
  - name: identity
    description: Browser sign-in and self-service API-key administration.
  - name: organizations
    description: >-
      Browser-only team organizations, invitations and membership
      administration.
  - name: launches
    description: Create an interactive sandbox from an agent manifest.
  - name: launch-runs
    description: >-
      Reserve, list, observe, and stop unattended multi-copy launch runs and
      their copies.
  - name: sandboxes
    description: Create and manage owned sandbox resources.
  - name: commands
    description: Execute Bash commands in an existing sandbox.
  - name: files
    description: Transfer exact file bytes within an existing sandbox.
  - name: providers
    description: Discover the caller's eligible supply and capabilities.
  - name: operations
    description: Reconcile uncertain mutations without replaying them.
  - name: provider-accounts
    description: >-
      Manage encrypted hosted BYOK connections separately from workload
      requests.
  - name: credits
    description: >-
      Prepaid credit balance, purchases and saved payment methods; never
      required for BYOK work.
  - name: spend-limits
    description: >-
      The cap on the managed compute a workspace can spend; BYOK work never
      counts.
  - name: processes
    description: >-
      Background commands with streamed output and completion; stdin where
      supported. A box whose route lacks the capability is refused with a typed
      error and a fix; see https://boxrouter.ai/docs/provider-support.
  - name: previews
    description: >-
      URLs and enforced credentials for sandbox ports. A box whose route lacks
      the capability is refused with a typed error and a fix; see
      https://boxrouter.ai/docs/provider-support.
  - name: volumes
    description: >-
      BoxRouter Volumes: one folder with checkpoints, restorable where a route
      can mount one. Any other route refuses the request with 409
      volume_unavailable; match with the volume lists the routes that can.
  - name: terminals
    description: >-
      Real PTY sessions through a guest helper. A box whose route lacks the
      capability is refused with a typed error and a fix; see
      https://boxrouter.ai/docs/provider-support.
  - name: secrets
    description: Manage workspace-scoped secret values without returning them.
  - name: artifacts
    description: Temporary workspace-owned inputs for provider builds and file transfers.
  - name: pricing
    description: >-
      The providers' published prices, as dated versions anyone can read without
      a key.
  - name: github
    description: >-
      The shared GitHub App connection used by Deployments and Actions;
      installations remain workspace-scoped.
  - name: actions
    description: >-
      GitHub Actions settings, policy previews and workspace-owned run, job and
      placement projections.
  - name: routing
    description: >-
      Workspace-wide routing authority, per-provider funding order and
      availability preview.
  - name: images
    description: Prepare and remove workspace-scoped provider copies of images.
paths:
  /actions/providers:
    get:
      tags:
        - actions
      summary: List the providers that run Actions
      description: >
        Public: needs no key or session. Lists each listed provider that runs
        Actions runners, how a

        new workspace pays for it (`supply`) and the runner image profiles it
        serves (`profiles`).

        A provider that is not publicly listed is left out. A workspace's own
        readiness

        (`getActionsReadiness`) is still the answer for what it can run now. Not
        paginated; the

        response may be cached for a minute.
      operationId: listActionsProviders
      responses:
        '200':
          description: The providers that run Actions.
          headers:
            Cache-Control:
              description: Caching directive; the list may be reused for a minute.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionsProviderPage'
        '429':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
      security: []
      x-codeSamples:
        - lang: python
          label: Python
          source: |
            from boxrouter import BoxRouter

            with BoxRouter() as client:
                result = client.api.actions.providers()
        - lang: typescript
          label: TypeScript
          source: |
            import { BoxRouter } from '@boxrouter/sdk';

            await using client = new BoxRouter();
            const result = await client.api.actions.providers();
        - lang: CLI
          label: CLI
          source: |
            boxrouter api actions providers
        - lang: curl
          label: HTTP
          source: |
            curl "https://api.boxrouter.ai/api/v1/actions/providers" \
              -H "Authorization: Bearer $BOXROUTER_API_KEY"
components:
  schemas:
    ActionsProviderPage:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          type: array
          description: >-
            One entry per provider that runs Actions here, in provider order.
            Not paginated. Empty when none does.
          items:
            $ref: '#/components/schemas/ActionsProvider'
    ActionsProvider:
      type: object
      additionalProperties: false
      required:
        - provider
        - provider_label
        - supply
        - profiles
      properties:
        provider:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-z][a-z0-9-]*$
        provider_label:
          type: string
          minLength: 1
          maxLength: 128
        supply:
          type: array
          minItems: 1
          uniqueItems: true
          description: >-
            How a new workspace pays for this provider's runners. `managed` is
            Credits, which BoxRouter funds; `byok` is the workspace's own key
            for the provider.
          items:
            type: string
            enum:
              - managed
              - byok
            x-boxrouter-open-enum: true
        profiles:
          type: array
          minItems: 1
          uniqueItems: true
          description: The runner image profiles this provider serves.
          items:
            type: string
            enum:
              - linux-basic
              - full
            x-boxrouter-open-enum: true
    ApiErrorResponse:
      type: object
      required:
        - error
      description: >-
        The one error body every failing call answers. It leads with what to do:
        `retry` says whether to send the call again, `fix` says what to change,
        `outcome` says what happened, and `doc_url` links to the page that
        explains the code. Clients retry `retry: safe` for you with the same
        idempotency key.
      x-sandbox-provider-spec-codes:
        - no_eligible_route
        - knob_not_named
        - unrecognised_word
        - invalid_request
        - not_named
        - gate_unavailable
        - account_unhealthy
        - lifetime_limit
        - lifetime_used_up
        - not_running
        - invalid_state
        - sandbox_ended
        - not_found
        - provider_error
        - timeout
        - contract_violation
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
            - outcome
            - retry
            - retry_after_seconds
          properties:
            code:
              type: string
              description: >
                Stable machine category; the catalogue below lists every code
                with its HTTP status.

                Operation failures include invalid_request, invalid_state,
                not_found,

                no_eligible_route, capability_unavailable, contract_violation,
                resource_limit,

                timeout and provider_error. Hosted service failures add
                method_not_allowed,

                unauthenticated, forbidden, actions_sandbox_protected,

                insufficient_credit, spend_limit_exceeded,

                provider_not_enabled, credentials_rejected, conflict,
                rate_limited, provider_quota, request_timeout, overloaded,

                database_unavailable, payment_method_required, payment_declined,
                promotion_already_redeemed, account_exists, and internal_error.
                unsupported_feature and

                output_limit are earlier names still returned by some routes.

                Organization and membership operations also use
                organization_changed, last_admin,

                stale_membership, directory_managed and change_in_progress. Key
                ownership and

                invitation operations use idempotency_key_reused and conflict.

                Credit refunds and purchase quotes also use
                refund_window_closed,

                nothing_to_refund, refund_in_progress,

                purchase_in_progress, dispute_open, already_refunded,

                refund_amount_changed, refund_fee_unavailable, quote_changed,

                refund_rate_limit, refund_retry_requires_support,
                idempotency_key_reused and fraud_review.

                Card setup adds card_setup_rate_limit (429, with Retry-After): a
                workspace may start five

                card setups an hour.

                A provider account you connected that refuses the request for
                its own plan or quota limit

                answers 429 provider_quota with the provider's words in
                native_message; rate_limited is

                BoxRouter's own limit, or the request rate of a provider account
                you connected. A route

                paid with BoxRouter credits that is out of capacity answers 429
                quota_exceeded, and

                names no provider.

                Routing Prevent Overrides refuses a request containing
                preferences.order,

                preferences.sort or preferences.allow_fallbacks with
                routing_overrides_forbidden,

                outcome not_started and details.fields naming the prohibited
                inputs. No provider

                effect occurs.

                Launch operations also use invalid_request, secret_missing,
                agent_not_found,

                no_eligible_route and launch_failed.

                A process or terminal is observed by one API task. When that
                task stops, process

                output, result and stdin answer 410 process_observer_lost
                (reading or cancelling the

                process still works), and a terminal on a provider that cannot
                reattach it answers

                410 terminal_observer_lost. invalid_observer_hop (403) refuses
                an internal hop

                between API tasks that is not signed; clients never send one.

                Opening a preview that the provider answered with other access
                than the request

                asked for returns 502 preview_access_refused: that preview is
                never returned, and

                details say whether it was ended.

                Starting a process with wait_for_port answers 409
                port_not_listening, outcome partial,

                when the process exits before the port accepts connections or
                the port stays closed for

                30 seconds; the process is ended and details carry the output so
                far.

                A request that must store content (a volume, a saved artifact)
                under transient content

                retention answers 409 privacy_persistence_conflict with outcome
                not_started.

                A sandbox request that stops before anything is created also
                answers

                lifetime_cap_exceeded, knob_not_named and unrecognised_word
                (400), and price_unknown and

                policy_denied (409), each with outcome not_started; the Actions
                codes job_claim_lost,

                actions_authority_changed, actions_candidate_ceiling_withdrawn
                and

                actions_candidate_outside_ceiling (409) say the job's claim,
                settings or admitted routes

                changed; provider_budget_exhausted (409) says a run's provider
                budget allows no

                further create. A create that names an image Cloud cannot use
                answers 400

                image_architecture_unsupported, image_digest_resolution_failed,

                image_preparation_unsupported or
                private_image_managed_route_unavailable, and

                privacy_admission_unavailable when privacy cannot be enforced;
                each says what to change.

                A create whose own image build failed (a step of the Dockerfile
                ended with an error)

                answers 422 image_build_failed with outcome not_started: the
                same build would fail on

                every provider, so BoxRouter ends the create after the first
                build and tries no other

                provider. A base image a provider cannot pull (its own registry
                access or region), a

                provider's rate limit or any other provider fault is not that:
                those leave the next

                eligible provider to be tried.

                image_digest_resolution_failed means BoxRouter's own registry
                check could not read the

                image; it also ends the create at once, with no other provider
                tried.

                Launch and source-repository refusals name the repository or
                manifest fault (code_ref_not_found,

                code_repository_*, source_*, invalid_source_manifest,
                invalid_manifest_encoding,

                invalid_run_spec, repository_*, reserved_env_refused,
                launch_run_position_conflict,

                code_reference_moved, dockerfile_context_unsupported,
                image_tag_unresolved,

                recovery_sandbox_mismatch); the GitHub-side ones
                (source_rate_limited,

                source_resolution_failed, source_resolution_timeout,
                code_repository_resolution_failed)

                are safe to resend. image_setup_timeout,
                managed_funding_unavailable,

                lifetime_funding_conflict, candidate_admission_unavailable,
                secrets_unavailable and the

                Actions candidate codes (actions_candidate_record_invalid,
                actions_create_budget_exhausted,

                actions_create_format_mismatch) complete the creation and
                extension refusals.

                dispatch_limit_reached, inline_secret_values_refused and
                launch_incomplete come from

                launch runs, provider_policy_unknown from an operation whose
                privacy evidence cannot be

                verified, and quota_exceeded from a route paid with BoxRouter
                credits that has no capacity.

                Volume operations also use volume_busy, volume_lease_lost,
                volume_not_attached,

                volume_incompatible, volume_save_failed and
                volume_restore_failed. Creating a

                sandbox on a volume whose writer is ending waits for the release
                (at most 120

                seconds) before it can answer volume_busy.

                A team member's new personal API key is paused until WorkOS
                membership sync catches

                up: it answers 403 forbidden whose message and fix say the key
                becomes active once

                the team membership syncs, usually within a minute, and the call
                can be retried.

                Enabling an Actions repository that a GitHub installation covers
                answers 503

                github_unavailable when GitHub cannot confirm the installation's
                coverage or admin

                access: no binding is created, and the same call is safe to
                resend. Listing the

                repositories of an installation that GitHub no longer serves, or
                that belongs to another

                App, answers 502 github_installation_unreachable: disconnect the
                installation and

                connect it again. Any Actions call answers 503
                actions_unavailable, outcome

                not_started, when this deployment has no Actions service or
                cannot read the

                repository's stored settings; resending the same call does not
                help.

                Feedback sent from the website answers 422 message_required,
                message_too_long,

                contains_secret, reply_email_required or invalid_reply_email,
                each with outcome

                not_started; change the form, then send it again. A GitHub
                connection callback whose

                attempt expired answers 401 authentication_required: start the
                connection again. The

                routing preview answers 503 routing_preview_not_ready while
                Actions has not composed

                its read-only view yet (resend after a moment). 503
                routing_settings_unavailable and

                503 github_app_not_configured name a deployment that has no
                approved providers or no

                GitHub App configured; resending the same call does not help.

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

                excluded, closest and nearest; knob_not_named the knob and its
                values;

                unrecognised_word the path and the known words (never the word
                sent); not_named the gate, what

                the call needed beyond the grant and the corrected requirements
                line; gate_unavailable

                the gate and account; lifetime_limit the ceiling and this run. A
                creation that

                stopped before a sandbox existed may also carry
                `fallbacks_allowed`, `stopped_reason`

                and `attempts`, spelled and bounded as in the sandbox route
                selection.

                capability_unavailable may identify the needed capability. A
                launch preparation failure can follow sandbox creation;

                inspect outcome and cleanup details before creating another.
                Clients must

                preserve fields they do not know.
              properties:
                selection_version:
                  type: integer
                  minimum: 0
                  description: >-
                    Current selected organization version for
                    organization_changed.
                considered:
                  type: integer
                  minimum: 0
                  description: no_eligible_route only; how many routes were considered.
                excluded:
                  type: array
                  description: >-
                    no_eligible_route only; every considered route that cannot
                    serve the request. Each entry names its `provider` and the
                    checks it failed (`failed` for a sandbox request, `reasons`
                    and `exclusions` for a launch); clients must preserve fields
                    they do not know.
                  items:
                    type: object
                    required:
                      - provider
                    properties:
                      provider:
                        type: string
                closest:
                  type:
                    - object
                    - 'null'
                  description: >-
                    no_eligible_route only; the excluded route that fails fewest
                    checks, or null.
                nearest:
                  type: array
                  description: >-
                    no_eligible_route only; the smallest changes that would make
                    a route eligible, nearest first. An entry names the change
                    (`change` and `then_eligible` for a sandbox request,
                    `provider`, `distance` and `failing` for a launch); clients
                    must preserve fields they do not know.
                  items:
                    type: object
                requirement:
                  type: string
                  description: >-
                    The SandboxProviderSpec family whose requirement would make
                    this operation available.
                purchase_id:
                  type: string
                  description: >-
                    Retained failed credit purchase ID, when a saved-card charge
                    was declined.
                preview:
                  $ref: '#/components/schemas/CreditRefundPreview'
                  description: >-
                    Current refund preview returned with 409
                    refund_amount_changed.
                quote:
                  $ref: '#/components/schemas/CreditPurchaseQuote'
                  description: Current purchase quote returned with 409 quote_changed.
                redemption:
                  $ref: '#/components/schemas/CreditPromotion'
                  description: >-
                    Original promotion redemption returned with 409
                    promotion_already_redeemed.
                scope:
                  type: string
                  enum:
                    - workspace
                    - api_key
                    - person
                  x-boxrouter-open-enum: true
                  description: >-
                    What the refusal counts against. spend_limit_exceeded:
                    `workspace`, the configured cap that refused admission.
                    rate_limited: `api_key` when the key sent more requests at
                    once than a server starts together, or `person` when one
                    person made too many promo code attempts.
                period:
                  type: string
                  enum:
                    - total
                    - daily
                    - monthly
                  x-boxrouter-open-enum: true
                  description: spend_limit_exceeded only; the cap period that applies.
                limit_nanodollars:
                  type: integer
                  minimum: 1
                  description: spend_limit_exceeded only; exact configured USD nanodollars.
                requested_nanodollars:
                  type: integer
                  minimum: 1
                  description: spend_limit_exceeded only; exact proposed managed hold.
                sign_in_method:
                  type: string
                  description: >-
                    account_exists only: how the existing account with this
                    verified address signs in (google, github, email or other).
                masked_email:
                  type: string
                  description: >-
                    account_exists only: that account's address, masked as
                    `t…@gmail.com`.
                failure_reason:
                  type: string
                  maxLength: 100
                  description: >-
                    Short safe card-decline reason; raw Stripe messages are not
                    returned.
                names:
                  type: array
                  uniqueItems: true
                  items:
                    $ref: '#/components/schemas/SecretName'
                  description: All manifest secret names that could not be resolved.
                fields:
                  type: array
                  uniqueItems: true
                  items:
                    type: string
                    enum:
                      - preferences.order
                      - preferences.sort
                      - preferences.allow_fallbacks
                  description: >-
                    routing_overrides_forbidden only; the prohibited request
                    inputs.
                volume_id:
                  type: string
                  description: BoxRouter Volume ID involved in the error.
                writer_sandbox_id:
                  type: string
                  description: >-
                    volume_busy only; the sandbox that holds the volume's writer
                    lease, when it is a recorded sandbox.
                checkpoint:
                  type: integer
                  minimum: 1
                  description: Volume checkpoint involved in the error.
                limit_bytes:
                  type: integer
                  minimum: 0
                observed_bytes:
                  type: integer
                  minimum: 0
                mismatch:
                  type: object
                  additionalProperties: false
                  required:
                    - field
                    - recorded
                    - requested
                  properties:
                    field:
                      type: string
                      enum:
                        - image
                        - arch
                        - provider
                      x-boxrouter-open-enum: true
                    recorded:
                      type: string
                    requested:
                      description: >-
                        What the request asked for. A string for `image` and
                        `arch`. For `provider`, the list in `preferences.only`,
                        or else the request's `route` filter object, or null
                        when the request named neither. Clients must preserve
                        fields of the object they do not know.
                      oneOf:
                        - type: string
                        - type: array
                          items:
                            type: string
                        - type: object
                        - type: 'null'
                    eligible:
                      type: array
                      items:
                        type: string
                      description: >-
                        field `provider` only; the providers that can mount the
                        volume.
                volume_phase:
                  type: string
                  enum:
                    - check
                    - branch
                    - lease
                    - identity
                    - install
                    - credential
                    - mount
                    - metadata
                    - checkpoint
                    - commit
                    - write
                    - cold_resume
                  x-boxrouter-open-enum: true
                phase:
                  type: string
                  enum:
                    - code
                    - setup
                    - files
                    - background
                    - previews
                    - image.prepare
                  x-boxrouter-open-enum: true
                  description: Preparation phase that failed.
                command:
                  type: string
                  description: Command whose nonzero exit stopped launch preparation.
                exit_code:
                  type: integer
                  description: >-
                    Exit code of the failed command, or of the process that
                    exited before its port listened.
                stderr_tail:
                  type: string
                  description: >
                    At most the final 4 KiB of stderr from the failed command,
                    with resolved secret values

                    redacted. port_not_listening carries the same tail of the
                    process's stderr.
                stdout_tail:
                  type: string
                  description: >-
                    port_not_listening only; at most the final 4 KiB of the
                    process's stdout.
                agent:
                  type: string
                  description: Unknown catalog agent name.
                port:
                  type: integer
                  minimum: 1
                  maximum: 65535
                  description: >-
                    The sandbox port whose preview was refused
                    (preview_access_refused) or that never accepted connections
                    (port_not_listening).
                revoked:
                  type: boolean
                  description: >
                    preview_access_refused only; true when the unwanted preview
                    was ended and no

                    access to the port remains. False: it may still be reachable
                    (outcome unknown).
                preview_id:
                  type: string
                  description: >
                    preview_access_refused only; the identifier the provider
                    gave the preview that may

                    still be reachable. Present only for a public preview.
                url:
                  type: string
                  format: uri
                  description: >
                    preview_access_refused only; the address of a public preview
                    that may still be

                    reachable. Never present for a private preview, whose
                    address holds a credential,

                    and never when it was ended.
                reason:
                  type: string
                  enum:
                    - provider_account_disconnected
                    - lifetime_conflict
                    - snapshot_not_ready
                    - snapshot_pin_unavailable
                    - admission_changed
                    - owner_mismatch
                    - no_creation_origin
                    - no_frozen_funding
                    - window_mismatch
                    - price_book_unknown
                    - hold_mismatch
                    - unscoped_resend
                    - deadline_passed
                    - build_cutoff_passed
                    - purpose_not_budgeted
                    - budget_changed
                    - exhausted
                    - required_environment_missing
                    - agent_max_copies
                    - model_access_ambiguous
                    - max_copies_per_run
                    - creation_origin_index_unavailable
                    - snapshot_pin_missing
                    - snapshot_inventory_incomplete
                    - timing_keep_needs_native_timeout
                    - manifest_missing
                    - manifest_invalid
                    - privacy_content_profile_conflict
                    - privacy_origin_unknown
                    - launch_run_environment_encryption_unavailable
                  x-boxrouter-open-enum: true
                  description: >
                    Which cause of the code, spelled for programs. Present only
                    on the codes listed here.

                    conflict: provider_account_disconnected (the provider
                    account of the chosen route was

                    disconnected or removed; nothing started), lifetime_conflict
                    (a lifetime key was reused

                    with a different request, or an extension is unresolved),
                    snapshot_not_ready (the

                    snapshot is not ready; `state` is its state),
                    snapshot_pin_unavailable (the snapshot's

                    own account, class and region cannot serve this request).
                    lifetime_funding_conflict:

                    admission_changed, owner_mismatch, no_creation_origin,
                    no_frozen_funding, window_mismatch,

                    price_book_unknown or hold_mismatch name the funding check
                    that failed.

                    provider_budget_exhausted: exhausted, deadline_passed,
                    build_cutoff_passed,

                    purpose_not_budgeted, budget_changed or unscoped_resend name
                    the cap that refused.

                    invalid_request: required_environment_missing (`names`),
                    agent_max_copies,

                    model_access_ambiguous (`names`). run_limit_exceeded:
                    max_copies_per_run (`limit`).

                    managed_funding_unavailable:
                    creation_origin_index_unavailable. capability_unavailable:

                    snapshot_pin_missing, snapshot_inventory_incomplete,
                    timing_keep_needs_native_timeout.

                    invalid_run_spec: manifest_missing, manifest_invalid.
                    privacy_persistence_conflict

                    (privacy_content_profile_conflict only),
                    provider_policy_unknown (privacy_origin_unknown)

                    and secrets_unavailable
                    (launch_run_environment_encryption_unavailable) add a value
                    only

                    where it says more than the code.
                    inline_secret_values_refused, reserved_env_refused and

                    authorization_refused send none.

                    Clients must tolerate values they do not know. A failed
                    image build reports its own

                    words in `build_output`, not here.
                build_output:
                  type: string
                  maxLength: 300
                  description: >-
                    image_build_failed only; the build's own error words, at
                    most 300 characters.
                path:
                  type: string
                  description: >-
                    The request field the refusal is about, a dotted path of the
                    contract's own field names (for example `lifetime_seconds`
                    or `registry_credentials`). For a launch's source repository
                    and Dockerfile build context refusals it is instead the file
                    path inside the caller's own repository or upload
                    (invalid_source_manifest, source_file_not_found,
                    repository_file_unsupported, invalid_request about the
                    context). It never repeats a label, metadata or other key
                    name the caller chose, or any value.
                known:
                  type: array
                  items:
                    type: string
                  description: unrecognised_word only; the words the field accepts.
                limit:
                  type: integer
                  description: >-
                    The cap that refused the request, counted in `unit`.
                    lifetime_cap_exceeded: the longest lifetime the fitting
                    routes allow. lifetime_limit: the longest single run.
                unit:
                  type: string
                  description: >-
                    What `limit` counts, for example bytes, api_keys, seconds or
                    requests per minute. lifetime_cap_exceeded also sends it
                    with `step_mismatches`, which count in `unit`.
                usage:
                  type: integer
                  description: >-
                    resource_limit and lifetime_limit; how much of `limit` is
                    already used, in `unit`. For lifetime_limit it is the
                    seconds this run has already used.
                limit_source:
                  type: string
                  enum:
                    - workspace_spend_limit
                    - credit_balance
                  x-boxrouter-open-enum: true
                  description: >-
                    spend_limit_exceeded and insufficient_credit; what stopped
                    the request.
                spent_nanodollars:
                  type: integer
                  minimum: 0
                  description: Already counted against `limit_nanodollars`.
                available_nanodollars:
                  type: integer
                  minimum: 0
                  description: insufficient_credit only; the balance the request could use.
                account_caps:
                  type: array
                  description: >-
                    lifetime_cap_exceeded; the provider accounts you connected
                    whose cap is shorter than the lifetime you asked for. Empty
                    when every fitting route is paid with credits.
                  items:
                    type: object
                    required:
                      - provider
                      - account_id
                      - limit
                    properties:
                      provider:
                        type: string
                      account_id:
                        type: string
                      limit:
                        type: integer
                        minimum: 1
                        description: That account's longest lifetime, counted in `unit`.
                step_mismatches:
                  type: array
                  description: >-
                    lifetime_cap_exceeded; the provider accounts you connected
                    that accept lifetimes only in whole steps. Empty when every
                    fitting route is paid with credits.
                  items:
                    type: object
                    required:
                      - provider
                      - account_id
                      - step
                    properties:
                      provider:
                        type: string
                      account_id:
                        type: string
                      step:
                        type: integer
                        minimum: 1
                        description: >-
                          The step, counted in `unit`; the lifetime must be a
                          multiple of it.
                providers:
                  type: array
                  items:
                    type: string
                  description: >-
                    credentials_rejected only; the providers whose key you
                    connected and which rejected it. Never sent for a route paid
                    with credits.
                retry_after_seconds:
                  type: integer
                  minimum: 0
                  description: >-
                    Seconds to wait before sending the same request again; the
                    same wait as the Retry-After header.
                reset_at:
                  type: string
                  format: date-time
                  description: When the limit that refused the request next restarts.
                home_region:
                  type: string
                  description: >-
                    wrong_region only; the region the organization is served
                    from.
                requirements:
                  type:
                    - object
                    - 'null'
                  description: >-
                    not_named only; the whole requirements line to send next
                    time.
                gate:
                  type: string
                  description: not_named and gate_unavailable; the gate the call used.
                missing:
                  type:
                    - object
                    - 'null'
                  description: not_named only; what the call needed beyond the grant.
                still_eligible:
                  type: integer
                  minimum: 0
                  description: >-
                    not_named only; how many routes still fit the corrected
                    requirements.
                fits_here:
                  type: boolean
                  description: >-
                    not_named only; whether this sandbox's own route fits the
                    corrected requirements.
                exclusion:
                  type: object
                  description: >-
                    no_eligible_route only; present when Cloud's own rules kept
                    the one provider the request pinned out, so a caller can
                    record the cell as excluded rather than failed.
                  required:
                    - provider
                    - kinds
                    - reasons
                  properties:
                    provider:
                      type: string
                    kinds:
                      type: array
                      items:
                        type: string
                        enum:
                          - health_hidden
                          - go_live_evidence
                          - standard_image_unready
                        x-boxrouter-open-enum: true
                    reasons:
                      type: array
                      items:
                        type: string
                        enum:
                          - provider_hidden
                          - section_unproven
                          - standard_image_unavailable
                        x-boxrouter-open-enum: true
                attempts:
                  type: array
                  description: >-
                    A creation that stopped before a sandbox existed; the
                    dispatch attempts in order.
                  items:
                    $ref: '#/components/schemas/CreationAttempt'
                fallbacks_allowed:
                  type: boolean
                  description: The effective allow_fallbacks after inheritance.
                stopped_reason:
                  $ref: '#/components/schemas/CreationStoppedReason'
                state:
                  type: string
                  description: >-
                    not_running, invalid_state, snapshot_not_ready; the state
                    the resource was in (the values of the sandbox `state`, or
                    of the snapshot's).
                state_reason:
                  type:
                    - string
                    - 'null'
                  description: >-
                    sandbox_ended, not_running and invalid_state; why it is in
                    that state (the values of the sandbox `state_reason`), null
                    when none.
                ended_at:
                  type:
                    - string
                    - 'null'
                  format: date-time
                  description: sandbox_ended only; when the sandbox ended.
                sandbox_id:
                  type: string
                  description: >-
                    launch_failed and launch_incomplete; the sandbox to read or
                    delete.
                sandbox_ids:
                  type: array
                  items:
                    type: string
                  description: >-
                    conflict (account in use); the live sandboxes that block the
                    request.
                operations:
                  type: array
                  description: >-
                    conflict (account in use); operations whose outcome is not
                    known yet, to read one by one.
                  items:
                    type: object
                    required:
                      - id
                      - operation
                    properties:
                      id:
                        type: string
                      operation:
                        type: string
                      sandbox_id:
                        type:
                          - string
                          - 'null'
                cleanup:
                  type: string
                  enum:
                    - confirmed
                    - pending
                    - not_required
                    - uncertain
                  x-boxrouter-open-enum: true
                  description: >-
                    launch_failed and an interrupted launch; whether the sandbox
                    the launch created is gone. `confirmed`: deleted. `pending`:
                    deletion is still queued. `not_required`: nothing was
                    created. `uncertain`: not confirmed, so check the sandbox.
                recovery_id:
                  type: string
                  description: >-
                    An interrupted launch; the operation to read for the cleanup
                    result.
                upload_ids:
                  type: array
                  items:
                    type: string
                  description: volume_busy only; the uploads that hold the volume.
                prerequisite:
                  type: string
                  description: >-
                    A command that could not start; the prerequisite that
                    failed.
                command_started:
                  type: boolean
                  const: false
                  description: >-
                    A command that could not start; always false, so sending it
                    again is safe.
            request_id:
              type: string
            doc_url:
              type:
                - string
                - 'null'
              format: uri
              description: >-
                Where the documentation explains this code:
                `https://boxrouter.ai/docs/error-codes#` followed by the code,
                for example
                `https://boxrouter.ai/docs/error-codes#no_eligible_route`. The
                page has one anchored row per code with what it means and what
                to do. BoxRouter sends it with every error; it is null for a
                code that has no documented row. Clients must accept an error
                body that omits it.
            fix:
              type:
                - string
                - 'null'
              minLength: 1
              description: >-
                Actionable change for the caller when the request cannot be
                completed. A refusal (4xx) always carries one; a server or
                provider fault, including an error event that ends a terminal or
                process stream, can answer null.
            operation_id:
              type:
                - string
                - 'null'
              description: >-
                Durable server operation ID for reconciliation after uncertain
                mutations.
            outcome:
              type: string
              enum:
                - not_started
                - completed
                - partial
                - unknown
              description: >
                What is known about the requested side effect. `not_started`
                means nothing ran

                anywhere, at BoxRouter or at a provider; a launch-setup or
                process-start failure

                after dispatch is `partial` or `unknown`. Unknown and partial
                forbid automatic

                replay and always carry `retry: check_outcome`. An HTTP status
                alone does not establish

                outcome.

                Many refusals report not_started before the provider is asked
                anything. A read

                (GET or HEAD) has no side effect to be unsure about, so its
                failures report

                not_started and carry the code's own retry value. A launch
                preparation failure

                happens after the sandbox was created and setup commands may
                already have run, and

                deleting the sandbox does not undo effects outside it: it
                reports partial once the

                cleanup is confirmed and unknown if it is not. A process that
                wait_for_port ended

                reports partial. volume_restore_failed on a resume or create,

                and volume_save_failed after the guest was read, report unknown
                or partial; they

                carry the operation_id when the call was recorded, and their fix
                does not offer to

                send the call again unchanged.
            retry:
              type: string
              enum:
                - safe
                - after_fix
                - check_outcome
                - never
              x-boxrouter-open-enum: true
              description: >
                What the caller may do next, fixed per code
                (x-boxrouter-error-retry): safe resends the

                same request, after_fix changes the request or setup first,
                check_outcome reads

                `outcome` and the resource before resending, never does not
                resend. Branch on this

                instead of the HTTP status.
            retry_after_seconds:
              type:
                - integer
                - 'null'
              minimum: 0
              description: >-
                How long to wait before a `retry: safe` resend, as the
                Retry-After header says it; null when there is no wait to name.
            owner:
              type: string
              enum:
                - provider
                - boxrouter
                - caller
              x-boxrouter-open-enum: true
              description: >
                Who owns the failure, decided from BoxRouter's own
                classification of it: `provider` when

                a provider's service failed, timed out, or refused for its own
                limit (rate or quota);

                `caller` when the request, or the caller's own account, key,
                credential or balance, must

                change; `boxrouter` for everything else, BoxRouter's own faults
                and limits. Branch on

                this to count a failure against the right party; `code` says
                what happened. BoxRouter

                Cloud always sends it; it is optional here only so that stored
                bodies from before it

                existed stay valid.
            provider:
              type:
                - string
                - 'null'
            provider_code:
              type:
                - string
                - 'null'
              description: >-
                The provider's own machine-readable error code, unchanged, when
                the provider gave one; null otherwise. It is the value
                `native_code` carries, with credential-shaped strings removed.
                Any provider's code is possible, so treat it as an opaque
                string.
            native_code:
              type:
                - string
                - 'null'
              description: >-
                The provider's machine-readable error code, unchanged, when it
                reports one.
            native_status:
              type:
                - integer
                - 'null'
              description: >-
                The provider's HTTP status, unchanged, when the failure came
                from a provider response.
            native_message:
              type:
                - string
                - 'null'
              maxLength: 4096
              description: >-
                The provider's own error message when it answered with an HTTP
                4xx refusal (for example a plan limit); null otherwise. Capped
                at 512 characters, with whitespace collapsed. Credential secrets
                and token-shaped strings are removed before return. The literal
                `[redacted]` marker is used when all credential secret fields
                are at least 12 characters; legacy saved secrets shorter than 12
                characters are removed without the marker.
    CreditRefundPreview:
      type: object
      additionalProperties: false
      required:
        - unused
        - held_excluded
        - fee
        - principal
        - tax
        - total
        - card
      properties:
        unused:
          type: integer
          minimum: 0
          description: Unused purchased credit in US cents, before held credit is excluded.
        held_excluded:
          type: integer
          minimum: 0
          description: Credit held for running sandboxes, in US cents.
        fee:
          type: integer
          minimum: 0
          description: Original Stripe processing fee retained, in US cents.
        principal:
          type: integer
          minimum: 0
          description: Tax-exclusive principal returned to the original card, in US cents.
        tax:
          type: integer
          minimum: 0
          description: Tax Stripe adds to the credit note, in US cents.
        total:
          type: integer
          minimum: 0
          description: Total Stripe will refund, in US cents.
        card:
          $ref: '#/components/schemas/MaskedCreditCard'
    CreditPurchaseQuote:
      type: object
      additionalProperties: false
      required:
        - amount
        - tax
        - total
        - address_required
      x-boxrouter-purchase-terms:
        fee_rate: '0.05'
        minimum_minor: 500
      properties:
        amount:
          type: integer
          minimum: 1
          description: >-
            Tax-exclusive credit amount in US cents; this is what is added to
            the balance.
        fee_minor:
          type: integer
          minimum: 0
          description: >-
            BoxRouter's purchase fee in US cents, computed by the server and
            charged on top of amount. Tax applies to amount plus fee. Absent on
            older services.
        tax:
          type: integer
          minimum: 0
          description: Estimated tax in US cents, on the credits and the fee.
        total:
          type: integer
          minimum: 1
          description: >-
            Estimated total to charge in US cents: amount plus fee_minor plus
            tax.
        address_required:
          type: boolean
        missing:
          type: array
          items:
            type: string
          description: Required billing address fields missing for an exact tax quote.
    CreditPromotion:
      type: object
      additionalProperties: false
      required:
        - code
        - amount_nanodollars
        - description
        - redeemed_at
      properties:
        code:
          type: string
          description: The code in its canonical upper-case form.
        amount_nanodollars:
          type: string
          maxLength: 19
          pattern: >-
            ^(?:[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-7])$
          description: >-
            Credit granted, in billionths of a US dollar, as a canonical
            positive signed 64-bit nanodollar string.
        description:
          type: string
          description: What the credit is for, as the promotion describes it.
        redeemed_at:
          type: string
          format: date-time
    SecretName:
      type: string
      minLength: 1
      maxLength: 128
      pattern: ^[A-Z][A-Z0-9_]{0,127}$
    CreationAttempt:
      type: object
      additionalProperties: false
      required:
        - provider
        - outcome
        - native_code
        - native_status
      description: >
        One provider dispatch made while creating, in dispatch order, including
        the one that

        created the sandbox. `outcome` is the operation vocabulary: completed,
        not_started

        (a definite refusal before any allocation), unknown and partial. Native
        refusal

        evidence is present only for a durable definite refusal. The route,
        account and supply

        name what was dispatched, not a confirmed binding, which is reported
        separately on the

        sandbox or placement. Payer, child and native payload identifiers are
        never returned.
      properties:
        provider:
          type: string
          minLength: 1
        outcome:
          type: string
          enum:
            - completed
            - not_started
            - unknown
            - partial
        native_code:
          type:
            - string
            - 'null'
        native_status:
          type:
            - integer
            - 'null'
        route_id:
          type:
            - string
            - 'null'
          maxLength: 128
          description: The route this dispatch used.
        account_id:
          type:
            - string
            - 'null'
          maxLength: 128
          description: The connected account this dispatch used.
        supply:
          type:
            - string
            - 'null'
          maxLength: 32
          description: 'The funding authority of this dispatch: byok or managed.'
        cause:
          $ref: '#/components/schemas/CreationRouteCause'
      allOf:
        - if:
            properties:
              outcome:
                enum:
                  - completed
                  - unknown
                  - partial
            required:
              - outcome
          then:
            properties:
              native_code:
                type: 'null'
              native_status:
                type: 'null'
    CreationStoppedReason:
      type:
        - string
        - 'null'
      enum:
        - fallbacks_disabled
        - no_eligible_route
        - uncertain_outcome
        - authority_changed
        - deadline_reached
        - cancelled
        - null
      x-boxrouter-open-enum: true
      description: >
        Why creation stopped dispatching further routes: `fallbacks_disabled`
        (allow_fallbacks was

        false and the one permitted dispatch was refused), `no_eligible_route`
        (every remaining

        route was excluded), `uncertain_outcome` (a dispatch may have allocated;
        never retried, reconcile

        with the operation), `authority_changed` (account, funding or privacy
        authority no longer

        permits the next route), `deadline_reached` and `cancelled`. Null when a
        route created the

        sandbox. Clients must tolerate values they do not know.
    MaskedCreditCard:
      type: object
      additionalProperties: false
      properties:
        brand:
          type:
            - string
            - 'null'
          description: Card brand; absent for Link methods.
        last4:
          type:
            - string
            - 'null'
          pattern: ^[0-9]{4}$
          description: Last four card digits; absent for Link methods.
        type:
          type: string
          enum:
            - card
            - link
          x-boxrouter-open-enum: true
        email:
          type: string
          format: email
          description: Link account email; present only when type is link.
      allOf:
        - if:
            properties:
              type:
                const: link
            required:
              - type
          then:
            required:
              - email
            properties:
              brand:
                type: 'null'
              last4:
                type: 'null'
        - if:
            properties:
              type:
                const: card
            required:
              - type
          then:
            required:
              - brand
              - last4
            properties:
              brand:
                type: string
              last4:
                type: string
                pattern: ^[0-9]{4}$
    CreationRouteCause:
      type: string
      minLength: 1
      maxLength: 64
      enum:
        - key_rejected
        - plan_unbuildable
        - privacy_denied
        - not_ready
        - not_dispatched
        - provider_create_failed
      x-boxrouter-open-enum: true
      description: >
        Why one route did not create the sandbox, in a bounded word:
        `key_rejected` (the provider

        refused the saved key), `plan_unbuildable` (the route matched but its
        create could not be

        built), `privacy_denied` (the workspace's privacy settings refused the
        route),

        `not_ready` (the route's provider session was not ready in time),
        `not_dispatched`

        (refused locally before any provider call) and `provider_create_failed`
        (the provider was

        asked and the create failed). Clients must tolerate values they do not
        know.
  responses:
    Error:
      description: >
        Structured error. `retry` says whether to send the call again (`now`,
        `after_fix`, `inspect` or `never`) and `retry_after_seconds` how long to
        wait first. Unowned and unknown resource IDs both return 404. Admission
        overload returns 503 with code overloaded, outcome not_started and
        Retry-After. It reserves no operation and dispatches no provider work.
        Shared workspace/provider admission budgets return 429 with code
        rate_limited, outcome not_started and Retry-After. An incomplete request
        body can return 408 request_timeout before dispatch. Durable-state
        failures return 503 database_unavailable with outcome unknown; do not
        infer that execution did not occur. A read (GET or HEAD) that meets the
        same failure changed nothing: its message says the state is temporarily
        unavailable, and it is safe to repeat. A provider that cannot be reached
        when a create is prepared returns 502 provider_error with outcome
        not_started; nothing was created, and the create can be retried with the
        same Idempotency-Key or sent to another provider with `providers`.

        Native errors are sanitized; upstream credentials, request bodies and

        another workspace's metadata are never included. Server-Timing is
        present only when the response reached Dispatcher or held-response
        preparation; an earlier response, including pre-Dispatcher admission
        overload, may omit it.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Server-Timing:
          $ref: '#/components/headers/ServerTiming'
        Retry-After:
          description: >-
            Seconds before retrying an eligible read; not permission to replay a
            mutation.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
  headers:
    RequestId:
      description: >-
        Server-generated correlation identifier; contains no credentials or
        payloads.
      schema:
        type: string
    ServerTiming:
      description: >
        Durations of server-side phases, for diagnosing slow requests. Phase
        names are not stable

        and may change.
      schema:
        type: string
      x-boxrouter-server-timing:
        version: 1
        unit: ms
        serviceAggregateMetric: service
        maxHeaderBytes: 8192
        maxOperationRows: 32
        decimalPlaces: 3
        safeNamePattern: ^[A-Za-z0-9_.:-]{1,64}$
        aggregates:
          - metric: service
            fieldStem: cloud
          - metric: database
            fieldStem: database
          - metric: code
            fieldStem: code
          - metric: provider_connect
            fieldStem: provider_connect
          - metric: provider_wait
            fieldStem: provider_wait
          - metric: accept
            fieldStem: accept
          - metric: queue
            fieldStem: queue
          - metric: admission
            fieldStem: admission
          - metric: encode
            fieldStem: encode
        aggregateGrammar:
          duration:
            parameter: dur
            type: number
            finite: true
            minimum: 0
          descriptionParameter: desc
          unknownDescription: unknown
          missingMeans: unreported
        operationGrammar:
          metric: op
          nameParameter: desc
          namePattern: safeNamePattern
          start:
            parameter: start
            type: number
            finite: true
            sign: signed
            relativeTo: recorderWindow
          duration:
            parameter: dur
            type: number
            finite: true
            minimum: 0
          outcomeParameter: outcome
          outcomes:
            - returned
            - raised
          requiresAggregateDependencyUnion: false
        omissionGrammar:
          metric: op-omitted
          count:
            parameter: desc
            type: integer
            minimum: 0
          duration:
            parameter: dur
            type: number
            finite: true
            minimum: 0
            sumOf: knownOmittedMeasuredRows
          requiresAggregateDependencyUnion: false
        coverageGrammar:
          metric: op-coverage
          descriptionParameter: desc
          unknownValue: unknown
          absentState: unreported
          states:
            - unknown
            - unreported
          absenceImpliesCompleteness: false
  securitySchemes:
    BoxRouterKey:
      type: http
      scheme: bearer
      description: BoxRouter API key; never an upstream provider key.
    BrowserSession:
      type: apiKey
      in: cookie
      name: __Host-boxrouter_session
      description: >-
        HttpOnly server-side session. Local HTTP uses boxrouter_session. Browser
        mutations require the session CSRF token and the configured Origin;
        execution API keys cannot administer sessions or customer keys.

````

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