#Error Handling

AIO Sandbox APIs expose several layers of errors. A robust client should not rely on HTTP status alone.

#Recommended Order

1. Check the HTTP status code.
2. If the response is JSON, check success.
3. For execution APIs, inspect domain fields such as status, exit_code, stdout, and stderr.
4. For WebSocket and streaming APIs, handle connection close and partial output separately.

#HTTP Errors

Common HTTP failures include:

#Tool-Level Errors

Some APIs can return HTTP 200 while reporting a tool failure:

{
  "success": false,
  "message": "command failed",
  "data": null
}

Treat success: false as a handled operation failure. Show message to the user or pass it back to your agent.

#Execution Errors

Shell, Bash, Jupyter, Node.js, and unified code execution may return process-level details:

{
  "success": true,
  "data": {
    "status": "finished",
    "exit_code": 1,
    "stdout": "",
    "stderr": "command not found"
  }
}

For these APIs, success: true only means the sandbox handled the request. The executed command or code can still fail.

#Client Pattern

def assert_sandbox_response(response):
    if getattr(response, "success", True) is False:
        raise RuntimeError(response.message)

    data = getattr(response, "data", None)
    if data is not None and getattr(data, "exit_code", 0) not in (0, None):
        raise RuntimeError(getattr(data, "stderr", "execution failed"))

    return data

#Further Reading

• Bash Pipe
• Shell Terminal
• Unified Code Execution
• Authentication