[MAINT] Discuss and clear out bugs reported in the documentation

[ethouris]

In the documentation there are several things marked as BUG?. These are problems like:

• inappropriate error code
• incorrectly reported problem
• unexpected, illogical or inconsistent behavior, in comparison to other similar functions

This is expected to be cleared up by:

1. Changing the design and behavior
2. Changing the error code or method of reporting

It should be done with little to no impact on the current users of the API.