The colloquial meaning of an error is perhaps not well aligned with zig’s error unions. Zig’s error unions could be used to mean “bad thing happened” but it doesn’t fit all use cases. The current design of errors is closer to “a refusal to return a value”. Its like returning null but you have the ability to switch on the errors for control flow.
In the issue, Andrew says “error codes are for control flow”. One could also interpret this as “error codes are not informative”, or “error codes are not values”.
If you are tempted to return a value with an error, consider if you should instead return a union. Being tempted to return a value could be an indication that you are attempting to hide or categorize information that should be part of the normal control flow of the program.
At least this is how I interpret how API’s should be designed under “error codes are for control flow”.