The error handling docs are out of date

The error handling docs date back to the early error redesign
work and don't match up with the route we actually took.  This
brings them in line with actual practice both for external users
and internal implementors, and notes some of the exceptions and
possible bugs.