Errors

The error envelope

Every non-2xx response from the application API and from the cell gateway has the same body:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again later.",
    "request_id": "req-9b0e1d2c3f4a5b6c7d8e9f00",
    "retryable": true,
    "details": { "retry_after_seconds": 42 }
  }
}

Treat a code or reason you do not know as a generic error: show message and use retryable. New reasons can appear at any time within /v1.

A few 502, 503 or 504 responses from the network edge carry a different body. Treat them as retryable. The SDKs raise ShardfluxProtocolError for them.

Retrying

The TypeScript and Python SDKs apply these rules for you. They send a request refused with 429 quota_exceeded or 503 host_capacity again whatever its method, after the full Retry-After, for up to admissionTimeoutMs / admission_timeout (2 minutes by default; TypeScript 0.22.0+, Python 0.18.0+).

Application API codes

Codes returned by https://api.shardflux.dev/v1:

Requests with an API key never receive token_invalid, invalid_credentials, mfa_required, email_unverified, step_up_required or the browser sign-in codes: they come from /v1/auth and from requests with a person's CLI session (Authorization: Bearer sfu_...; see Authentication). The console's own routes also use csrf_failed, which /v1 never returns.

Cell gateway codes

Codes returned by a workspace's cell_endpoint (exec, files, terminals, processes, git, browser):

Computer use (/computer, /computer/actions, /computer/stream):

The cell enum also contains capacity_pending; the gateway never returns it.

Reasons

details.reason refines a code. The tables list the reasons a request with an API key can meet; the last one adds those of a person's session.

402 entitlement_required

402 card_required

Opening, resuming or forking a workspace, or building a template, in an organization without a card on file. details.add_card_url is the console's Usage & billing page for that organization, where its creator saves a card on a Stripe page in setup mode (nothing is charged). From a person's session the same check is POST /v1/organizations/{id}/billing/card-checks: it returns the Stripe page (url), and GET .../card-checks/{card_check_id} reports succeeded once the card is saved. GET .../billing/subscription has card_required: true until then. Running workspaces keep running. A paid plan, or a plan arranged with Shardflux, counts as a card on file.

{"error":{"code":"card_required","message":"Compute runs on organizations with a card on file. The organization's creator saves one at https://app.shardflux.dev/billing?organization_id=01a1…&add_card=1; nothing is charged.","request_id":"req_…","retryable":false,"details":{"reason":"card_required","organization_id":"01a1…","plan":"free","add_card_url":"https://app.shardflux.dev/billing?organization_id=01a1…&add_card=1"}}}

402 allowance_exhausted

New opens, resumes and forks are refused, and the organization's running workspaces are suspended with their files, memory and processes kept. Nothing is deleted. See Overage. GPU-hours never refuse a start: used up, they stop only the GPU (GPU frame requests).

A time-limited plan grant counts usage across its whole grant window. Exhausting its CPU-hours or RAM GiB-hours ends the grant; waiting does not renew it, and workspace compute pauses until you choose a paid plan while up to 10 GiB of retained workspace storage is kept. When spend_cap is null, overage is unavailable.

GPU frame requests

A GPU app's control socket (/run/sfgpu/<pid>.sock) answers each frame request with one JSON line. When the platform does not render it, ok is false, status is 402 and retryable is false; the workspace and the app keep running, and rendering comes back on its own once the cause clears.

{"ok":false,"error":"allowance_exhausted","status":402,"retryable":false,"reason":"allowance_used","message":"..."}

The organization's usage summary shows the same state: gpu.cap_state is gpu_blocked and gpu.blocked_reason is the reason.

GPU video sessions

Video sessions are counted per workspace (Limits). A create past the workspace's count, or one that finds no session free on its GPU within the admission wait, is refused, and nothing is created:

GPU readbacks

A GPU app that waits for GPU results (Blender with SFGPU_READBACK=1, compute results read from mapped memory) or for the GPU itself (a CUDA call) takes its turn when the GPU is busy. A Vulkan readback that gets no GPU within 10 minutes ends with VK_ERROR_DEVICE_LOST, and the app's log has a [sfgpu] readback: line with the reason. Start the render again; the next one waits its turn the same way.

403 quota_exceeded

429 rate_limited

Platform request and workspace-credential budgets return rate_limited, retryable: true, and a Retry-After header with the delay in seconds, also in details.retry_after_seconds. Honor that delay before retrying.

details.rate_limit identifies resource, scope (api_key, organization, or workspace), limit, window_seconds, burst, plan_key, catalog_version, and workspace_units. Keys in the same organization share its organization budget; rotating keys does not increase it. These budgets are separate from plan usage allowances and concurrent workspace admission.

429 quota_exceeded

Returned when a request would make one more workspace work than the organization's plan allows at once:

• by the cell gateway, for a call that would wake a parked workspace. The call waits up to 5 seconds for a workspace to stop working first; calls to a workspace that is already working never wait.
• by the API, for an open, resume or fork (details.limit: concurrent_workspaces). The request waits up to 10 seconds for a workspace to stop working first; reopening a workspace that is already running never waits.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Your plan allows 10 workspaces working at once and none became free within 5 seconds; retry shortly, or upgrade.",
    "request_id": "req-9b0e1d2c3f4a5b6c7d8e9f00",
    "retryable": true,
    "details": { "limit": "concurrent_workspaces", "limit_value": 10, "current": 10, "retry_after_seconds": 2 }
  }
}

• The request was refused before anything ran or started, so any request is safe to retry after Retry-After (also in details.retry_after_seconds): opens, commands, stdin, terminals and file writes included. The SDKs retry it: the cell gateway's since TypeScript 0.14.0 and Python 0.10.0, the API's from TypeScript 0.22.0 and Python 0.18.0. From those versions on, both are retried for up to admissionTimeoutMs / admission_timeout (2 minutes by default).
• The API's refusal also carries details.plan.
• A tool call, a keepalive and a wake hint can get it; a wake hint gets it at once, without the wait.
• A WebSocket attach (exec output, terminal) is refused with the same 429 response. From a browser, the connection opens, sends this body as its first text message and closes with code 4429, whose close reason is compact JSON with code and retryable. The SDKs read both and raise the error with its own code and details (TypeScript 0.22.0+, Python 0.18.0+).

403 forbidden

404 not_found

409 conflict

Two retryable 409s have no reason: a request whose Idempotency-Key is still in progress, and an open of a key that another open is creating at the same moment. Retry the same request (with the same key).

422 validation_failed

Workspaces, inputs and secrets:

On a resize with at_least: true, a smaller disk_gib leaves the disk unchanged and allows the other named resources to grow. A resize without that flag keeps the shrink_not_supported response for a smaller disk.

Workspace tools (the cell gateway):

Templates and builds:

Egress policy validation returns every problem in details.issues, each with path, reason and message.

Spend policy (overage and its spend cap, changed by an owner or billing member; details.field names the field):

507 workspace_disk_full

For a reachable workspace with an exhausted filesystem, the files API can read and remove files without starting an exec session. Cleanup exec sessions use bounded memory-backed control storage and output; their session labels include shardflux.session_storage: memory_until_cold_boot. They survive an agent restart or memory resume; a cold boot ends the processes and clears those emergency session records. Ordinary exec sessions keep their durable storage. Freeing filesystem space restores ordinary writes and exec storage. If the workspace cannot resume, contact support with the request id; credential delivery still requires writable space.

503 dependency_unavailable

details.reason: budget_backend_busy or budget_policy_unavailable means request-budget accounting is temporarily unavailable. The error is retryable, with a one-second Retry-After and details.retry_after_seconds. Back off and retry; this does not mean the plan allowance is exhausted.

File tools, parking and hosts

Reasons of the cell gateway for search, patches and reads of sleeping workspaces, for parked workspaces and for writes under immutable paths:

Inbound ports

Reasons of the ports routes of the API:

Answers of a port URL itself carry the header x-shardflux-reason; a response without it came from your app. The body is the usual error envelope (an HTML page when a browser asks for one):

File-first workspaces

Reasons of the API and the cell gateway for file-first workspaces:

An execution that ended failed or lost published nothing. Its result carries error with code, message, retryable (whether a new execution may succeed) and details.reason, for example exec_failed_to_start or layout_unsupported.

With a person's session

Account actions on /v1 need a person's CLI session (sfu_..., from /v1/auth or shard auth login); an API key gets 403 forbidden for them. These are the reasons they, and signing up, add to the tables above:

Operation errors

A failed operation (state: failed or canceled) carries error: {code, message, retryable, details}. The SDKs raise it as OperationFailedError (errorCode, retryable).

Durable copy of a suspend

A suspend succeeds once the workspace is sealed on its host; its checkpoint then reaches durable storage (Durable storage). The suspend operation stays succeeded in every case; its result.durability.state tells the rest.

Waiting for the copy (suspend({ durable: true }), waitForDurable(), suspend(durable=True), wait_for_durable()):

• DurabilityLostError (TypeScript 0.12.0+, Python 0.8.0+): durability.state became lost. It carries the operation and durability (with reason).
• OperationTimeoutError with durable: true: the wait's timeoutMs / timeout ran out while the copy was pending. The suspend has succeeded and the copy continues; wait again with waitForDurable(err.operationId) / wait_for_durable(err.operation_id).
• The CLI (--durable, 0.7.0+) and the MCP server (durable: true, 0.6.0+) report both as errors naming the operation and durability.state: code durability_lost (details.state lost, details.reason; CLI exit 6) and code timeout with details {durable: false, state: "pending"} (CLI exit 5; keep waiting with shard operations wait <id> --durable or operation_wait with durable: true).

While an operation is capacity_pending, error.details shows where it stands: queue_position (its place in line), deadline_at (it moves later while new capacity starts) and pool.scale_out (requested while new capacity is starting, with pool.expected_ready_by).

Operation state_reason values are progress, not errors: no_ready_host while capacity_pending (waiting for a host), storage_host_unavailable while capacity_pending (the workspace's disk is being reattached; the start continues by itself), preserving_files while capacity_pending (the workspace's files are being moved to new storage; the start continues by itself once they are, and its deadline_at is an hour after its creation), lease_renewing while capacity_pending (the host is picking up the organization's current usage allowance; the start continues by itself), template_downloading while running (the host is fetching the template).

Template builds from a workspace or a draft report failure.code on the build: source_unavailable (the capture failed or the checkpoint is gone), resource_limit (details.limit: template_org_bytes_max or template_file_entries_max), scan_failed (the credential scan found secrets: the paths are listed; build again with acknowledged_scan_findings), compatibility_failed and publish_failed.

Builds of a template with immutable paths, from any source, also report:

Client errors

The clients add their own errors for failures that never reached the API:

• TypeScript SDK: ExecStartError (0.10.0+: a command that could not start; a ShardfluxApiError with exec_failed_to_start), OperationFailedError, OperationTimeoutError, DurabilityLostError (0.12.0+), ShardfluxProtocolError, ToolArgumentError, CheckoutTimeoutError (0.9.0+) and the template errors (reference). NotSupportedForModeError and TreeRevisionMismatchError (0.9.0+) are ShardfluxApiErrors for not_supported_for_mode and tree_revision_mismatch; the SDK raises the first before sending a call the mode does not have (local: true).
• Python SDK: the same classes under ShardfluxError, with CheckoutTimeoutError, NotSupportedForModeError and TreeRevisionMismatchError from 0.5.0, ExecStartError from 0.6.0 and DurabilityLostError from 0.8.0 (reference).
• CLI: exit codes and local codes such as usage, interrupted and (0.5.0+) checkout_ended and execution_failed (an execution that ended failed or lost, exit 6) (reference).
• MCP server: invalid_arguments, workspace_pinned, timeout, operation_failed and others. An error result carries the refusal's reason, and from 0.4.0 a hint for the file-first and host refusals (reference).

Do not infer workspace deletion from 404

A bodiless/proxy 404 is a protocol failure. Even a structured not_found can mean a stale route or inaccessible scope. TypeScript 0.12.0 and Python 0.8.0 protocol errors include the responding source. isWorkspaceGone(err) / is_workspace_gone(err) is true only for an explicit API conflict with reason workspace_deleted. It is never true for a protocol error or cell not_found. Do not delete user data based on HTTP status alone.

failed is recoverable through resume or auto-wake with the same workspace ID and disk. It is not a tombstone. The workspace's failure carries the error of the operation that failed it (for example vm_start_failed with details.host_reason) until a start succeeds. Conditional idle suspension that loses the race to work is canceled before capture (workspace_active), leaving the workspace running.

Retention validation

422 validation_failed, details.reason: retention_requires_persistent means retention was requested for a session workspace. Use a persistent workspace to keep its state and have it deleted after 1 through 3650 idle days. Day values outside that integer range are 422 validation_failed. A retention setter on a deleted workspace returns 409 conflict, details.reason: workspace_deleted; open its key to start a fresh workspace.

Missing files

TypeScript SDK 0.16.0+ raises FileNotFoundError, a ShardfluxApiError, when a requested file path is missing. Python 0.12.0+ exposes shardflux.FileNotFoundError, inheriting both builtin FileNotFoundError and ShardfluxApiError. Catch it to create a file or ask for another path. Workspace deletion and protocol errors remain separate errors.

Tunnel replay

A cell conflict with details.reason=tunnel_replay_unavailable means the tunnel's retained output is unavailable. Open a fresh forward connection. Reverse tunnel handles in TypeScript SDK 0.27.3+, Python 0.24.0+ and CLI 0.24.1+ replace the listener automatically; their existing TCP peers reset.