docs(storage): Improve error inspection documentation (#12301)

frq-dev · web-flow · commit 420da1a64ac4 · 2025-06-05T18:22:41.000-04:00
* docs(storage): Improve error introspection documentation

* docs(storage): Improve error inspection documentation

* Corrected and added additional info  about errors

* fixed formatting and updated errors due to new auth library
diff --git a/storage/doc.go b/storage/doc.go
@@ -274,15 +274,43 @@ To generate the signature, you must have:
 
 # Errors
 
-Errors returned by this client are often of the type [googleapi.Error].
-These errors can be introspected for more information by using [errors.As]
-with the richer [googleapi.Error] type. For example:
+Errors returned by this client are often of the type [github.com/googleapis/gax-go/v2/apierror].
+The [apierror.APIError] type can wrap a [google.golang.org/grpc/status.Status]
+if gRPC was used, or a [google.golang.org/api/googleapi.Error] if HTTP/REST was used.
+You might also encounter [googleapi.Error] directly from HTTP operations.
+These types of errors can be inspected for more information by using [errors.As]
+to access the specific underlying error types and retrieve detailed information,
+including HTTP or gRPC status codes. For example:
+
+	// APIErrors often wrap a googleapi.Error (for JSON and XML calls) or a status.Status (for gRPC calls)
+	var ae *apierror.APIError
+	if ok := errors.As(err, &ae); ok {
+		// ae.HTTPCode() is the HTTP status code.
+		// ae.GRPCStatus().Code() is the gRPC status code
+		log.Printf("APIError: HTTPCode: %d, GRPCStatusCode: %s", ae.HTTPCode(), ae.GRPCStatus().Code())
+
+		if ae.GRPCStatus().Code() == codes.Unavailable {
+			// ... handle gRPC unavailable ...
+		}
+	}
 
+	// This allows a user to get more information directly from googleapi.Errors (for JSON/XML calls)
 	var e *googleapi.Error
 	if ok := errors.As(err, &e); ok {
-		  if e.Code == 409 { ... }
+		// e.Code is the HTTP status code.
+		// e.Message is the error message.
+		// e.Body is the raw response body.
+		// e.Header contains the HTTP response headers.
+		log.Printf("HTTP Code: %d, Message: %s", e.Code, e.Message)
+
+		if e.Code == 409 {
+			// ... handle conflict ...
+		}
 	}
 
+This library may also return other errors that are not wrapped as [apierror.APIError]. For
+example, errors with authentication may return [cloud.google.com/go/auth.Error].
+
 # Retrying failed requests
 
 Methods in this package may retry calls that fail with transient errors.
