Context

Errors returned by Go Driver APIs are difficult to handle. Users have to know what error types to check for and/or what error helper functions to use (e.g. mongo.IsTimeout). Many errors lose context as they're returned through the layers of logic, meaning the error messages don't describe what actually happened.

Additionally, error messaging in the Go Driver has historically been difficult and error-prone because of functions like replaceErrors and processWriteError, which make it extremely difficult to comprehend what error values will actually be returned. There are a some better options for handling errors like this:

1. Don't break out error types in the "x/" (i.e. internal but exported) packages. Define one or a few error types that communicate the error information and break them out into more usable error types that are all defined in the mongo package.
2. Define error interfaces in the mongo package that define expected error methods instead of error types. Assert that the errors satisfy the expected interfaces in the mongo package.

   package mongo
   
   type ExternalError interface {
   	ErrorInfo() 
   }
   
   var _ ExternalError = driver.InternalError
   

   That allows using errors.As like

   var exterr ExternalError
   if errors.As(err, &exterr) {
   	exterr.ErrorInfo()
   	// ...
   

We should try to unify the error handling logic across all Go Driver APIs and include comprehensive instructions for how to handle errors in the docs. Make sure to consider the different permutations of how users might run operations, including:

• With/without transactions.
• With/without explicit sessions.
• With/without CSFLE.

Open questions:

• Which approach supports all of our error handling requirements?
• Which approach is the simplest to implement? To maintain? To use?

Definition of done

• Pick an approach for error handling that doesn't require implementing a function like replaceErrors, and implement it. Also, experimental/internal packages cannot reference symbols in the stable packages, so it must be done in a way that doesn't require all packages to reference one symbol.
• Remove the the replaceErrors function.

Pitfalls