[twhitmore]

The examples at the start seem confused & poor. A type that "can return either one result, many results or an error" is trying to fit two different cardinalities into a single API.

APIs should either be typed to be unary (possibly with optionality/ error), or plural (allowing 0..many).

I've dealt with similar woolly design before. Introducing clear distinction between cardinalities gave a major improvement in logical clarity.