Skip to main content
A 200 from POST /v1/workspaces/{workspace_id}/shell means the server ran the line, not that the line succeeded: check exit_code. Every HTTP error answers JSON in one shape, on both servers. Requests past a limit answer 429 with Retry-After (rate limits).

Error body

Detect an error by its HTTP status, never by the presence of an error key: a success body can carry an error field of its own, such as a finished line’s error in GET /v1/workspaces/{workspace_id}/lines/{line_id}.

Status codes

A route that needs a running workspace answers 409 workspace_stopped when your workspace is stopped. A workspace that does not exist, or that you may not see, is 404 not_found. A failed file call picks its code from its POSIX condition: Each endpoint’s Errors section lists its documented failures. The complete OpenAPI contract retains every response schema. Some bodies are not this shape. The RPC and MCP endpoints answer JSON-RPC errors. A failed file call carries the inner object above, {code, message, errno, decision}, in an RPC error’s data, and as the text of a failed MCP vfs_<call> tool. Records inside an NDJSON stream follow the stream’s own format once the 200 is sent. The readiness endpoint answers 503 with {"status": "full"} or {"status": "shutting_down"} when the server cannot accept new workspaces.

Which error is reported

A response reports one error, the first one found:
  1. Query and path parameters, before the body.
  2. The body’s declared fields, in the order the endpoint’s schema lists them.
  3. Unknown keys, last, in the order they appear in the body.
The server reads a body as JSON whatever its Content-Type says, except multipart/* and application/octet-stream, so curl -d works without a header. Request-shape errors use these messages, where <param> is the field’s path: <expected> is a string, an integer, a number, a boolean, an object, an array or one of a, b, c.

Examples

Missing or invalid credentials

A request without a valid token returns HTTP 401 with WWW-Authenticate: Bearer:
Supply a valid token before retrying. See Authentication.

Workspace identifier conflict

Creating demo again with a different configuration returns HTTP 409:
Choose another identifier for a different workspace. Retrying the original configuration with the same identifier returns HTTP 200 and the existing workspace, with the same response shape as a successful 201 creation.

Invalid request field

Sending a numeric workspace id returns HTTP 400:
Change id to a string before retrying.

Unknown runtime or machine

A shell request whose runtime or machine the workspace does not have is refused with HTTP 400 before anything runs:
The message lists the names the workspace has, or says the field must be unset when the workspace has none.

Policy refusal of a file call

A VFS call a policy refuses returns HTTP 403:
A shell line a policy refuses still returns 200; check its decision.

Failed shell job

A shell job that fails inside the server returns HTTP 500 with the fixed message:
The job’s own error stays readable as error in GET /v1/workspaces/{workspace_id}/lines/{line_id}, and in the final record of a stream. Check for side effects before retrying.

Shell exit codes

A completed shell request can return HTTP 200 with a nonzero exit_code. Inspect exit_code, stdout, stderr and decision before treating the command as successful. The response’s HTTP status describes the request, while exit_code describes the shell command.