diff --git a/cmd/onecli/auth.go b/cmd/onecli/auth.go
index 214214b..8f94729 100644
--- a/cmd/onecli/auth.go
+++ b/cmd/onecli/auth.go
@@ -3,6 +3,7 @@ package main
 import (
 	"bufio"
 	"errors"
+	"fmt"
 	"os"
 	"strings"
 
@@ -60,7 +61,11 @@ func (c *AuthLoginCmd) Run(out *output.Writer) error {
 	client := api.New(config.APIHost(), apiKey)
 	user, err := client.GetUser(newContext())
 	if err != nil {
-		return errors.New("invalid API key: authentication failed")
+		var apiErr *api.APIError
+		if errors.As(err, &apiErr) && apiErr.StatusCode == 401 {
+			return errors.New("invalid API key: the server rejected this key")
+		}
+		return fmt.Errorf("could not verify API key: %w", err)
 	}
 
 	// Store the key.
diff --git a/cmd/onecli/run.go b/cmd/onecli/run.go
index 422a6a2..699ae47 100644
--- a/cmd/onecli/run.go
+++ b/cmd/onecli/run.go
@@ -47,7 +47,7 @@ func (c *RunCmd) Run(out *output.Writer) error {
 	// Resolve the binary path early — fail fast before the API round-trip.
 	binary, err := exec.LookPath(c.Args[0])
 	if err != nil {
-		return fmt.Errorf("command not found %s: %w", c.Args[0], err)
+		return fmt.Errorf("command not found: %s — is it installed and in your PATH?", c.Args[0])
 	}
 
 	// Fetch gateway configuration from the API.
@@ -124,7 +124,7 @@ func (c *RunCmd) Run(out *output.Writer) error {
 	// Exec — replaces this process so the agent gets direct terminal control.
 	out.Stderr(fmt.Sprintf("onecli: gateway connected. Starting %s...", c.Args[0]))
 	if err := syscall.Exec(binary, c.Args, env); err != nil {
-		return fmt.Errorf("exec %s: %w", binary, err)
+		return fmt.Errorf("could not start %s: %w", c.Args[0], err)
 	}
 	return nil
 }
diff --git a/internal/api/client.go b/internal/api/client.go
index 96221ca..a331165 100644
--- a/internal/api/client.go
+++ b/internal/api/client.go
@@ -144,7 +144,7 @@ func (c *Client) do(ctx context.Context, method, path string, body any, result a
 
 	if result != nil {
 		if err := json.Unmarshal(respBody, result); err != nil {
-			return fmt.Errorf("decoding response: %w", err)
+			return fmt.Errorf("unexpected response from server (status %d) — expected JSON", resp.StatusCode)
 		}
 	}
 	return nil