Update types documentation

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

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

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

The issue names no files, tests, or entry points; start by locating the API error-handling code and the types documentation. Clarify which error cases and message details are in scope, then verify the documented behavior and corresponding error messages.

Written by the indexing model from the issue text.