Update api documentation

**Problem**
When working with auth, the error messages could be more descriptive.

**Suggestion**
Improve error handling and add detailed error messages.

**Context**
This would help with debugging and maintenance.

Start by locating the API authentication error handling and the related documentation; the issue names no files, tests, or entry points. Confirm the intended error cases with a maintainer, then document the agreed detailed messages and verify that the API documentation matches the resulting behavior.

Written by the indexing model from the issue text.