Errors

A 200 from POST /v1/workspaces/{workspace_id}/shell means the server ran the line, not that the line succeeded: check exit_code. Most API errors return JSON with a detail message, but an auth or Host refusal can be plain text, so check Content-Type before parsing. The full status table is in Errors; requests past a limit answer 429 with Retry-After (rate limits).

HTTP status codes

Status	Meaning	Recovery
`400`	Malformed request, disallowed host or disallowed browser origin.	Check the body, API host and browser origin.
`401`	Missing or incorrect token.	Send a valid bearer token; sign in again if it expired.
`403`	A policy or mount mode refused the call.	Check workspace policies and mount permissions.
`404`	The workspace, session, job or file does not exist.	Verify the identifier or file path.
`409`	An identifier is taken, the workspace is busy or a file changed since it was read.	Resolve the conflict before retrying; see the workspace example below.
`422`	Request fields failed validation.	Correct the fields named in `detail`.
`429`	A rate limit or session limit was reached.	Respect `Retry-After` when present; reduce the request rate or close unused sessions.
`501`	A saved-config operation requires a server configured for one account.	Check the deployment’s saved-configuration support.
`503`	The server reached its workspace limit or is shutting down.	Retry after capacity or availability recovers.

Each endpoint’s Errors section lists its documented failures. The complete OpenAPI contract retains every response schema. JSON errors can include errno and refusal alongside detail. Those fields describe filesystem errors and policy refusals when available. The readiness endpoint uses a different body: HTTP 503 returns {"status": "full"} or {"status": "shutting_down"} when the server cannot accept new workspaces.

Examples

Missing or invalid credentials

The TypeScript daemon returns HTTP 401 with JSON:

{"detail": "Unauthorized"}

The Python daemon returns the same status with Content-Type: text/plain:

Unauthorized

Check Content-Type before decoding the body. Supply a valid token before retrying. See Authentication.

Workspace identifier conflict

Creating demo again with a different configuration returns HTTP 409:

{"detail": "workspace id already exists: 'demo'"}

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 422:

{
  "detail": [
    {
      "type": "string_type",
      "loc": ["body", "id"],
      "msg": "Input should be a valid string",
      "input": 4
    }
  ]
}

loc identifies the invalid field. Change id to a string before retrying. Validation messages can differ between server implementations.

Shell exit codes

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

HTTP API

Resources

HTTP status codes

Examples

Missing or invalid credentials

Workspace identifier conflict

Invalid request field

Shell exit codes

​HTTP status codes

​Examples

​Missing or invalid credentials

​Workspace identifier conflict

​Invalid request field

​Shell exit codes

HTTP status codes

Examples

Missing or invalid credentials

Workspace identifier conflict

Invalid request field

Shell exit codes