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:- Query and path parameters, before the body.
- The body’s declared fields, in the order the endpoint’s schema lists them.
- Unknown keys, last, in the order they appear in the body.
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 HTTP401 with
WWW-Authenticate: Bearer:
Workspace identifier conflict
Creatingdemo again with a different configuration returns HTTP 409:
200 and the existing
workspace, with the same response shape as a successful 201 creation.
Invalid request field
Sending a numeric workspaceid returns HTTP 400:
id to a string before retrying.
Unknown runtime or machine
A shell request whoseruntime or machine the workspace does not have is
refused with HTTP 400 before anything runs:
Policy refusal of a file call
A VFS call a policy refuses returns HTTP403:
200; check its decision.
Failed shell job
A shell job that fails inside the server returns HTTP500 with the fixed
message:
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 HTTP200 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.