We use MongoAPIError interchangeably with MongoParseError when parsing connection string, and, moreover, the connection string module has its own version of the MongoParseError. It would be good to standardize the returned error from validating MongoClient options to at least extend from the same class in all of these different cases. We should probably have a separate type for connection string validation errors because we also use MongoParseError when we are literally unable to parse a message (from, e.g. message_stream), so we should not use a "parse error" in situations where we are able to parse options but they happen to be invalid.

Any connection string validation should extend from MongoAPIError.

Unknowns

• Name and hierarchy of the new error type. MongoURIParseError / MongoConnectionStringParseError were proposed in 2023, with the objection that additional "parse" error types do not address the problem, since these are validation failures rather than parse failures. Unresolved, and blocks implementation.
• Whether to replace mongodb-connection-string-url's own MongoParseError or rewrap its errors driver-side. Rewrapping avoids changing a module.

Acceptance Criteria

Implementation Requirements

• Introduce a distinct error type for connection string and option validation failures, extending MongoAPIError
• Convert the validation throws in connection_string.ts and utils.ts to the new type
• Leave message_stream.ts throwing MongoParseError; those are genuine parse failures on OP_MSG / OP_COMPRESSED

Testing Requirements

• Update tests asserting MongoParseError for validation cases

Documentation Requirements

• Migration note: code catching MongoParseError for connection string validation must be updated

Follow Up Requirements

• Blocks NODE-5886, which adds new validation throw sites and should use the new type from the start