fix: address PR feedback - improve error messages and timeout consistency

- Add timeout configuration to get_access_token_for_connection for consistency
- Improve Content-Type parsing with explicit comments for lenient JSON detection
- Enhance unsupported type error messages to explain allowed types
- Clarify case-insensitive Bearer prefix check in error message and docs
- Fix docstring example to use async function context (avoid 'await outside async' warning)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: btiernay

README.md

@@ -166,7 +166,7 @@ asyncio.run(main())
 
 **Important:**
 - Client authentication is sent via HTTP Basic (`client_id`/`client_secret`), not in the form body.
-- Do not prefix `subject_token` with "Bearer " - send the raw token value only.
+- Do not prefix `subject_token` with "Bearer " - send the raw token value only (checked case-insensitively).
 - The `subject_token_type` must match a Token Exchange Profile configured in Auth0. This URI identifies which profile will process the exchange and **must not use reserved OAuth namespaces (IETF or vendor-controlled)**. Use your own collision-resistant namespace. See the [Custom Token Exchange documentation](https://auth0.com/docs/authenticate/custom-token-exchange) for naming guidance.
 - If neither an explicit `audience` nor tenant/Action logic sets it, you may receive a token not targeted at your API.
 

src/auth0_api_python/api_client.py

@@ -471,16 +471,17 @@ async def get_access_token_for_connection(self, options: dict[str, Any]) -> dict
             params["login_hint"] = options["login_hint"]
 
         try:
-            async with httpx.AsyncClient() as client:
+            async with httpx.AsyncClient(timeout=httpx.Timeout(self.options.timeout)) as client:
                 response = await client.post(
                     token_endpoint,
                     data=params,
                     auth=(client_id, client_secret)
                 )
 
                 if response.status_code != 200:
-                    error_data = response.json() if "json" in response.headers.get(
-                        "content-type", "").lower() else {}
+                    # Lenient check for JSON error responses (handles application/json, text/json, etc.)
+                    content_type = response.headers.get("content-type", "").lower()
+                    error_data = response.json() if "json" in content_type else {}
                     raise ApiError(
                         error_data.get("error", "connection_token_error"),
                         error_data.get(
@@ -596,7 +597,7 @@ async def example():
             )
         if tok.lower().startswith("bearer "):
             raise GetTokenByExchangeProfileError(
-                "subject_token must not include the 'Bearer ' prefix"
+                "subject_token must not include the 'Bearer ' prefix (case-insensitive check)"
             )
 
         # Require client credentials
@@ -649,7 +650,9 @@ async def example():
                 if response.status_code != 200:
                     error_data = {}
                     try:
-                        if "json" in response.headers.get("content-type", "").lower():
+                        # Lenient check for JSON error responses (handles application/json, text/json, etc.)
+                        content_type = response.headers.get("content-type", "").lower()
+                        if "json" in content_type:
                             error_data = response.json()
                     except ValueError:
                         pass  # Ignore JSON parse errors, use generic error message below
@@ -751,7 +754,8 @@ def _apply_extra(
             # Handle sequences (list, tuple, etc.) but reject mappings/sets/bytes
             if isinstance(v, (dict, set, bytes)):
                 raise GetTokenByExchangeProfileError(
-                    f"Parameter '{k}' has unsupported type {type(v).__name__}"
+                    f"Parameter '{k}' has unsupported type {type(v).__name__}. "
+                    "Only strings, numbers, booleans, and sequences (list/tuple) are allowed"
                 )
             elif isinstance(v, (list, tuple)):
                 if len(v) > MAX_ARRAY_VALUES_PER_KEY: