internal/api: consolidate error response handling for all handlers

- Ensure that all errors are wrapped correctly and served as a json
  error response.

Change-Id: I588552c755fb2135916da95dec6d37238d030d39
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/758821
Auto-Submit: Ethan Lee <ethanalee@google.com>
kokoro-CI: kokoro <noreply+kokoro@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

4 files changed, 101 insertions, 103 deletions

diff --git a/internal/api/api.go b/internal/api/api.go
index 62e5663f..31b325ba 100644
--- a/internal/api/api.go
+++ b/internal/api/api.go
@@ -8,6 +8,7 @@ import (
 	"bytes"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"net/http"
 	"strconv"
 	"strings"
@@ -33,24 +34,18 @@ func ServePackage(w http.ResponseWriter, r *http.Request, ds internal.DataSource
 
 	pkgPath := trimPath(r, "/v1/package/")
 	if pkgPath == "" {
-		return serveErrorJSON(w, http.StatusBadRequest, "missing package path", nil)
+		return fmt.Errorf("%w: missing package path", derrors.InvalidArgument)
 	}
 
 	var params PackageParams
 	if err := ParseParams(r.URL.Query(), &params); err != nil {
-		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+		return err
 	}
 
-	um, candidates, err := resolveModulePath(r, ds, pkgPath, params.Module, params.Version)
+	um, err := resolveModulePath(r, ds, pkgPath, params.Module, params.Version)
 	if err != nil {
-		if errors.Is(err, derrors.NotFound) {
-			return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil)
-		}
 		return err
 	}
-	if len(candidates) > 0 {
-		return serveErrorJSON(w, http.StatusBadRequest, "ambiguous package path", candidates)
-	}
 
 	// Use GetUnit to get the requested data.
 	fs := internal.WithMain
@@ -67,7 +62,7 @@ func ServePackage(w http.ResponseWriter, r *http.Request, ds internal.DataSource
 	bc := internal.BuildContext{GOOS: params.GOOS, GOARCH: params.GOARCH}
 	unit, err := ds.GetUnit(r.Context(), um, fs, bc)
 	if err != nil {
-		return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil)
+		return fmt.Errorf("%w: %s", derrors.Unknown, err.Error())
 	}
 
 	// Process documentation, including synopsis.
@@ -97,7 +92,7 @@ func ServePackage(w http.ResponseWriter, r *http.Request, ds internal.DataSource
 			// result.
 			gpkg, err := godoc.DecodePackage(d.Source)
 			if err != nil {
-				return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil)
+				return fmt.Errorf("%w: %s", derrors.Unknown, err.Error())
 			}
 			innerPath := internal.Suffix(unit.Path, unit.ModulePath)
 			modInfo := &godoc.ModuleInfo{ModulePath: unit.ModulePath, ResolvedVersion: unit.Version}
@@ -115,10 +110,10 @@ func ServePackage(w http.ResponseWriter, r *http.Request, ds internal.DataSource
 			case "html":
 				return errors.New("unimplemented")
 			default:
-				return serveErrorJSON(w, http.StatusBadRequest, "bad doc format: need one of 'text', 'md', 'markdown' or 'html'", nil)
+				return fmt.Errorf("%w: bad doc format: need one of 'text', 'md', 'markdown' or 'html'", derrors.InvalidArgument)
 			}
 			if err := renderDoc(dpkg, r); err != nil {
-				return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil)
+				return fmt.Errorf("%w: %s", derrors.Unknown, err.Error())
 			}
 			docs = sb.String()
 		}
@@ -157,12 +152,12 @@ func ServeModule(w http.ResponseWriter, r *http.Request, ds internal.DataSource)
 
 	modulePath := trimPath(r, "/v1/module/")
 	if modulePath == "" {
-		return serveErrorJSON(w, http.StatusBadRequest, "missing module path", nil)
+		return fmt.Errorf("%w: missing module path", derrors.InvalidArgument)
 	}
 
 	var params ModuleParams
 	if err := ParseParams(r.URL.Query(), &params); err != nil {
-		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+		return err
 	}
 
 	requestedVersion := params.Version
@@ -173,9 +168,6 @@ func ServeModule(w http.ResponseWriter, r *http.Request, ds internal.DataSource)
 	// For modules, we can use GetUnitMeta on the module path.
 	um, err := ds.GetUnitMeta(r.Context(), modulePath, modulePath, requestedVersion)
 	if err != nil {
-		if errors.Is(err, derrors.NotFound) {
-			return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil)
-		}
 		return err
 	}
 
@@ -209,25 +201,22 @@ func ServeModuleVersions(w http.ResponseWriter, r *http.Request, ds internal.Dat
 
 	path := trimPath(r, "/v1/versions/")
 	if path == "" {
-		return serveErrorJSON(w, http.StatusBadRequest, "missing path", nil)
+		return fmt.Errorf("%w: missing path", derrors.InvalidArgument)
 	}
 
 	var params VersionsParams
 	if err := ParseParams(r.URL.Query(), &params); err != nil {
-		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+		return err
 	}
 
 	infos, err := ds.GetVersionsForPath(r.Context(), path)
 	if err != nil {
-		if errors.Is(err, derrors.NotFound) {
-			return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil)
-		}
 		return err
 	}
 
 	resp, err := paginate(infos, params.ListParams, 100)
 	if err != nil {
-		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+		return err
 	}
 
 	return serveJSON(w, http.StatusOK, resp)
@@ -239,12 +228,12 @@ func ServeModulePackages(w http.ResponseWriter, r *http.Request, ds internal.Dat
 
 	modulePath := trimPath(r, "/v1/packages/")
 	if modulePath == "" {
-		return serveErrorJSON(w, http.StatusBadRequest, "missing module path", nil)
+		return fmt.Errorf("%w: missing module path", derrors.InvalidArgument)
 	}
 
 	var params PackagesParams
 	if err := ParseParams(r.URL.Query(), &params); err != nil {
-		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+		return err
 	}
 
 	requestedVersion := params.Version
@@ -254,9 +243,6 @@ func ServeModulePackages(w http.ResponseWriter, r *http.Request, ds internal.Dat
 
 	metas, err := ds.GetModulePackages(r.Context(), modulePath, requestedVersion)
 	if err != nil {
-		if errors.Is(err, derrors.NotFound) {
-			return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil)
-		}
 		return err
 	}
 
@@ -275,7 +261,7 @@ func ServeModulePackages(w http.ResponseWriter, r *http.Request, ds internal.Dat
 
 	resp, err := paginate(items, params.ListParams, 100)
 	if err != nil {
-		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+		return err
 	}
 
 	return serveJSON(w, http.StatusOK, resp)
@@ -287,11 +273,11 @@ func ServeSearch(w http.ResponseWriter, r *http.Request, ds internal.DataSource)
 
 	var params SearchParams
 	if err := ParseParams(r.URL.Query(), &params); err != nil {
-		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+		return fmt.Errorf("%w: %s", derrors.InvalidArgument, err.Error())
 	}
 
 	if params.Query == "" {
-		return serveErrorJSON(w, http.StatusBadRequest, "missing query", nil)
+		return fmt.Errorf("%w: missing query", derrors.InvalidArgument)
 	}
 
 	dbresults, err := ds.Search(r.Context(), params.Query, internal.SearchOptions{
@@ -320,7 +306,7 @@ func ServeSearch(w http.ResponseWriter, r *http.Request, ds internal.DataSource)
 
 	resp, err := paginate(results, params.ListParams, searchResultsPerPage)
 	if err != nil {
-		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+		return fmt.Errorf("%w: %s", derrors.InvalidArgument, err.Error())
 	}
 
 	return serveJSON(w, http.StatusOK, resp)
@@ -332,31 +318,22 @@ func ServePackageSymbols(w http.ResponseWriter, r *http.Request, ds internal.Dat
 
 	pkgPath := trimPath(r, "/v1/symbols/")
 	if pkgPath == "" {
-		return serveErrorJSON(w, http.StatusBadRequest, "missing package path", nil)
+		return fmt.Errorf("%w: missing package path", derrors.InvalidArgument)
 	}
 
 	var params SymbolsParams
 	if err := ParseParams(r.URL.Query(), &params); err != nil {
-		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+		return err
 	}
 
-	um, candidates, err := resolveModulePath(r, ds, pkgPath, params.Module, params.Version)
+	um, err := resolveModulePath(r, ds, pkgPath, params.Module, params.Version)
 	if err != nil {
-		if errors.Is(err, derrors.NotFound) {
-			return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil)
-		}
 		return err
 	}
-	if len(candidates) > 0 {
-		return serveErrorJSON(w, http.StatusBadRequest, "ambiguous package path", candidates)
-	}
 
 	bc := internal.BuildContext{GOOS: params.GOOS, GOARCH: params.GOARCH}
 	syms, err := ds.GetSymbols(r.Context(), pkgPath, um.ModulePath, um.Version, bc)
 	if err != nil {
-		if errors.Is(err, derrors.NotFound) {
-			return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil)
-		}
 		return err
 	}
 
@@ -374,7 +351,7 @@ func ServePackageSymbols(w http.ResponseWriter, r *http.Request, ds internal.Dat
 
 	resp, err := paginate(items, params.ListParams, 100)
 	if err != nil {
-		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+		return err
 	}
 
 	return serveJSON(w, http.StatusOK, resp)
@@ -386,12 +363,12 @@ func ServePackageImportedBy(w http.ResponseWriter, r *http.Request, ds internal.
 
 	pkgPath := trimPath(r, "/v1/imported-by/")
 	if pkgPath == "" {
-		return serveErrorJSON(w, http.StatusBadRequest, "missing package path", nil)
+		return fmt.Errorf("%w: missing package path", derrors.InvalidArgument)
 	}
 
 	var params ImportedByParams
 	if err := ParseParams(r.URL.Query(), &params); err != nil {
-		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+		return err
 	}
 
 	requestedVersion := params.Version
@@ -399,16 +376,10 @@ func ServePackageImportedBy(w http.ResponseWriter, r *http.Request, ds internal.
 		requestedVersion = version.Latest
 	}
 
-	um, candidates, err := resolveModulePath(r, ds, pkgPath, params.Module, requestedVersion)
+	um, err := resolveModulePath(r, ds, pkgPath, params.Module, requestedVersion)
 	if err != nil {
-		if errors.Is(err, derrors.NotFound) {
-			return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil)
-		}
 		return err
 	}
-	if len(candidates) > 0 {
-		return serveErrorJSON(w, http.StatusBadRequest, "ambiguous package path", candidates)
-	}
 	modulePath := um.ModulePath
 
 	limit := params.Limit
@@ -418,9 +389,6 @@ func ServePackageImportedBy(w http.ResponseWriter, r *http.Request, ds internal.
 
 	importedBy, err := ds.GetImportedBy(r.Context(), pkgPath, modulePath, limit)
 	if err != nil {
-		if errors.Is(err, derrors.NotFound) {
-			return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil)
-		}
 		return err
 	}
 
@@ -448,16 +416,16 @@ func ServeVulnerabilities(vc *vuln.Client) func(w http.ResponseWriter, r *http.R
 
 		modulePath := trimPath(r, "/v1/vulns/")
 		if modulePath == "" {
-			return serveErrorJSON(w, http.StatusBadRequest, "missing module path", nil)
+			return fmt.Errorf("%w: missing module path", derrors.InvalidArgument)
 		}
 
 		var params VulnParams
 		if err := ParseParams(r.URL.Query(), &params); err != nil {
-			return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+			return err
 		}
 
 		if vc == nil {
-			return serveErrorJSON(w, http.StatusNotImplemented, "vulnerability data not available", nil)
+			return fmt.Errorf("%w: vulnerability data not available", derrors.Unsupported)
 		}
 
 		requestedVersion := params.Version
@@ -479,7 +447,7 @@ func ServeVulnerabilities(vc *vuln.Client) func(w http.ResponseWriter, r *http.R
 
 		resp, err := paginate(items, params.ListParams, 100)
 		if err != nil {
-			return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+			return err
 		}
 
 		return serveJSON(w, http.StatusOK, resp)
@@ -495,7 +463,7 @@ func trimPath(r *http.Request, prefix string) string {
 // If the module path is not provided, it searches through potential candidate module paths
 // derived from the package path. If multiple valid modules contain the package, it returns
 // a list of candidates to help the user disambiguate the request.
-func resolveModulePath(r *http.Request, ds internal.DataSource, pkgPath, modulePath, requestedVersion string) (*internal.UnitMeta, []Candidate, error) {
+func resolveModulePath(r *http.Request, ds internal.DataSource, pkgPath, modulePath, requestedVersion string) (*internal.UnitMeta, error) {
 	if requestedVersion == "" {
 		requestedVersion = version.Latest
 	}
@@ -513,24 +481,28 @@ func resolveModulePath(r *http.Request, ds internal.DataSource, pkgPath, moduleP
 					PackagePath: pkgPath,
 				})
 			} else if !errors.Is(err, derrors.NotFound) {
-				return nil, nil, err
+				return nil, err
 			}
 		}
 
 		if len(validCandidates) > 1 {
-			return nil, validCandidates, nil
+			return nil, &Error{
+				Code:       http.StatusBadRequest,
+				Message:    "ambiguous package path",
+				Candidates: validCandidates,
+			}
 		}
 		if len(validCandidates) == 0 {
-			return nil, nil, derrors.NotFound
+			return nil, derrors.NotFound
 		}
-		return foundUM, nil, nil
+		return foundUM, nil
 	}
 
 	um, err := ds.GetUnitMeta(r.Context(), pkgPath, modulePath, requestedVersion)
 	if err != nil {
-		return nil, nil, err
+		return nil, err
 	}
-	return um, nil, nil
+	return um, nil
 }
 
 func serveJSON(w http.ResponseWriter, status int, data any) error {
@@ -544,12 +516,16 @@ func serveJSON(w http.ResponseWriter, status int, data any) error {
 	return err
 }
 
-func serveErrorJSON(w http.ResponseWriter, status int, message string, candidates []Candidate) error {
-	return serveJSON(w, status, Error{
-		Code:       status,
-		Message:    message,
-		Candidates: candidates,
-	})
+func ServeError(w http.ResponseWriter, err error) error {
+	var aerr *Error
+	if !errors.As(err, &aerr) {
+		status := derrors.ToStatus(err)
+		aerr = &Error{
+			Code:    status,
+			Message: err.Error(),
+		}
+	}
+	return serveJSON(w, aerr.Code, aerr)
 }
 
 // paginate returns a paginated response for the given list of items and pagination parameters.
@@ -566,7 +542,7 @@ func paginate[T any](all []T, lp ListParams, defaultLimit int) (PaginatedRespons
 		var err error
 		offset, err = strconv.Atoi(lp.Token)
 		if err != nil || offset < 0 {
-			return PaginatedResponse[T]{}, errors.New("invalid token")
+			return PaginatedResponse[T]{}, fmt.Errorf("%w: invalid token", derrors.InvalidArgument)
 		}
 	}
 
diff --git a/internal/api/api_test.go b/internal/api/api_test.go
index 9930e3c9..daf49910 100644
--- a/internal/api/api_test.go
+++ b/internal/api/api_test.go
@@ -200,9 +200,8 @@ func TestServePackage(t *testing.T) {
 			r := httptest.NewRequest("GET", test.url, nil)
 			w := httptest.NewRecorder()
 
-			err := ServePackage(w, r, ds)
-			if err != nil {
-				t.Fatalf("ServePackage returned error: %v", err)
+			if err := ServePackage(w, r, ds); err != nil {
+				ServeError(w, err)
 			}
 
 			if w.Code != test.wantStatus {
@@ -267,7 +266,7 @@ func TestServeModule(t *testing.T) {
 			name:       "bad version",
 			url:        "/v1/module/example.com?version=nope",
 			wantStatus: http.StatusNotFound,
-			want:       &Error{Code: 404, Message: "could not find module for import path example.com: not found"},
+			want:       &Error{Code: 404, Message: "ServeModule: could not find module for import path example.com: not found"},
 		},
 		{
 			name:       "module with readme",
@@ -287,9 +286,8 @@ func TestServeModule(t *testing.T) {
 			r := httptest.NewRequest("GET", test.url, nil)
 			w := httptest.NewRecorder()
 
-			err := ServeModule(w, r, ds)
-			if err != nil && w.Code != test.wantStatus {
-				t.Fatalf("ServeModule returned error: %v", err)
+			if err := ServeModule(w, r, ds); err != nil {
+				ServeError(w, err)
 			}
 
 			if w.Code != test.wantStatus {
@@ -331,6 +329,7 @@ func TestServeModuleVersions(t *testing.T) {
 		url        string
 		wantStatus int
 		wantCount  int
+		want       any
 	}{
 		{
 			name:       "all versions (cross-major)",
@@ -355,9 +354,8 @@ func TestServeModuleVersions(t *testing.T) {
 			r := httptest.NewRequest("GET", test.url, nil)
 			w := httptest.NewRecorder()
 
-			err := ServeModuleVersions(w, r, ds)
-			if err != nil && w.Code != test.wantStatus {
-				t.Fatalf("ServeModuleVersions returned error: %v", err)
+			if err := ServeModuleVersions(w, r, ds); err != nil {
+				ServeError(w, err)
 			}
 
 			if w.Code != test.wantStatus {
@@ -393,7 +391,6 @@ func TestServeModulePackages(t *testing.T) {
 			{UnitMeta: internal.UnitMeta{Path: modulePath + "/sub", Name: "pkg2"}},
 		},
 	})
-
 	for _, test := range []struct {
 		name       string
 		url        string
@@ -401,6 +398,7 @@ func TestServeModulePackages(t *testing.T) {
 		wantCount  int
 		wantTotal  int
 		wantToken  string
+		want       any
 	}{
 		{
 			name:       "all packages",
@@ -429,9 +427,8 @@ func TestServeModulePackages(t *testing.T) {
 			r := httptest.NewRequest("GET", test.url, nil)
 			w := httptest.NewRecorder()
 
-			err := ServeModulePackages(w, r, ds)
-			if err != nil && w.Code != test.wantStatus {
-				t.Fatalf("ServeModulePackages returned error: %v", err)
+			if err := ServeModulePackages(w, r, ds); err != nil {
+				ServeError(w, err)
 			}
 
 			if w.Code != test.wantStatus {
@@ -515,7 +512,7 @@ func TestServeSearch(t *testing.T) {
 
 			err := ServeSearch(w, r, ds)
 			if err != nil {
-				t.Fatalf("ServeSearch returned error: %v", err)
+				ServeError(w, err)
 			}
 
 			if w.Code != test.wantStatus {
@@ -588,7 +585,7 @@ func TestServeSearchPagination(t *testing.T) {
 			w := httptest.NewRecorder()
 
 			if err := ServeSearch(w, r, ds); err != nil {
-				t.Fatalf("ServeSearch error: %v", err)
+				ServeError(w, err)
 			}
 
 			if w.Code != http.StatusOK {
@@ -663,6 +660,7 @@ func TestServePackageSymbols(t *testing.T) {
 		wantStatus int
 		wantCount  int
 		wantName   string // Check name of the first symbol to verify build context
+		want       any
 	}{
 		{
 			name:       "default best match (linux)",
@@ -703,21 +701,36 @@ func TestServePackageSymbols(t *testing.T) {
 			name:       "not found build context",
 			url:        "/v1/symbols/example.com/pkg?version=v1.0.0&goos=darwin&goarch=amd64",
 			wantStatus: http.StatusNotFound,
+			want: &Error{
+				Code:    http.StatusNotFound,
+				Message: "ServePackageSymbols: not found",
+			},
 		},
 	} {
 		t.Run(test.name, func(t *testing.T) {
 			r := httptest.NewRequest("GET", test.url, nil)
 			w := httptest.NewRecorder()
 
-			err := ServePackageSymbols(w, r, ds)
-			if err != nil && w.Code != test.wantStatus {
-				t.Fatalf("ServePackageSymbols returned error: %v", err)
+			if err := ServePackageSymbols(w, r, ds); err != nil {
+				ServeError(w, err)
 			}
 
 			if w.Code != test.wantStatus {
 				t.Errorf("status = %d, want %d. Body: %s", w.Code, test.wantStatus, w.Body.String())
 			}
 
+			if test.want != nil {
+				if want, ok := test.want.(*Error); ok {
+					var got Error
+					if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+						t.Fatalf("json.Unmarshal: %v", err)
+					}
+					if diff := cmp.Diff(want, &got); diff != "" {
+						t.Errorf("mismatch (-want +got):\n%s", diff)
+					}
+				}
+			}
+
 			if test.wantStatus == http.StatusOK {
 				var got PaginatedResponse[Symbol]
 				if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
@@ -760,6 +773,7 @@ func TestServePackageImportedBy(t *testing.T) {
 		url        string
 		wantStatus int
 		wantCount  int
+		want       any
 	}{
 		{
 			name:       "all imported by",
@@ -772,9 +786,8 @@ func TestServePackageImportedBy(t *testing.T) {
 			r := httptest.NewRequest("GET", test.url, nil)
 			w := httptest.NewRecorder()
 
-			err := ServePackageImportedBy(w, r, ds)
-			if err != nil && w.Code != test.wantStatus {
-				t.Fatalf("ServePackageImportedBy returned error: %v", err)
+			if err := ServePackageImportedBy(w, r, ds); err != nil {
+				ServeError(w, err)
 			}
 
 			if w.Code != test.wantStatus {
@@ -817,6 +830,7 @@ func TestServeVulnerabilities(t *testing.T) {
 		url        string
 		wantStatus int
 		wantCount  int
+		want       any
 	}{
 		{
 			name:       "all vulns",
@@ -835,9 +849,8 @@ func TestServeVulnerabilities(t *testing.T) {
 			r := httptest.NewRequest("GET", test.url, nil)
 			w := httptest.NewRecorder()
 
-			err := ServeVulnerabilities(vc)(w, r, ds)
-			if err != nil && w.Code != test.wantStatus {
-				t.Fatalf("ServeVulnerabilities returned error: %v", err)
+			if err := ServeVulnerabilities(vc)(w, r, ds); err != nil {
+				ServeError(w, err)
 			}
 
 			if w.Code != test.wantStatus {
diff --git a/internal/api/params.go b/internal/api/params.go
index e126fb2a..255a6128 100644
--- a/internal/api/params.go
+++ b/internal/api/params.go
@@ -9,6 +9,8 @@ import (
 	"net/url"
 	"reflect"
 	"strconv"
+
+	"golang.org/x/pkgsite/internal/derrors"
 )
 
 // ListParams are common pagination and filtering parameters.
@@ -82,9 +84,12 @@ type VulnParams struct {
 func ParseParams(v url.Values, dst any) error {
 	val := reflect.ValueOf(dst)
 	if val.Kind() != reflect.Pointer || val.Elem().Kind() != reflect.Struct {
-		return fmt.Errorf("dst must be a pointer to a struct")
+		return fmt.Errorf("%w: dst must be a pointer to a struct", derrors.InvalidArgument)
+	}
+	if err := parseValue(v, val.Elem()); err != nil {
+		return fmt.Errorf("%w: %v", derrors.InvalidArgument, err)
 	}
-	return parseValue(v, val.Elem())
+	return nil
 }
 
 func parseValue(v url.Values, val reflect.Value) error {
diff --git a/internal/api/types.go b/internal/api/types.go
index 92569ab1..6af65e58 100644
--- a/internal/api/types.go
+++ b/internal/api/types.go
@@ -92,6 +92,10 @@ type Error struct {
 	Candidates []Candidate `json:"candidates,omitempty"`
 }
 
+func (e *Error) Error() string {
+	return e.Message
+}
+
 // Candidate is a potential resolution for an ambiguous path.
 type Candidate struct {
 	ModulePath  string `json:"modulePath"`