chore(api): document API error response contracts (#3917)

## Summary

Clarifies documented HTTP error responses while preserving Python
exception behavior.

## Changes

- Describe verified failure statuses, error envelopes and applicable
retry headers.
- Preserve existing Python client types and methods.

Co-authored-by: markstuart-oai <323302876+markstuart-oai@users.noreply.github.com>