refactor(errors): unify SDK error reporting on a central registry

Every failure path used to surface `code="Unknown"` with `status_code=-1`,
leaving callers unable to tell a bad request from a server fault. This routes
all of them through a single registry that separates the public code the caller
sees (`BadRequestError`, `RateLimitError`, ...) from the internal one used for
diagnosis (`sdk.agentic_rl.FunctionTestTimeout`, ...).

Public/internal split:
- Add `dashscope/common/error_registry.py` holding the public errors and the
  internal `sdk.*` definitions, each with a message, a solution and its
  substitution variables. The file is generator output; all fixes here land on
  the consumer side.
- AgentStudio and AgenticRL classify by server code only, so a status can no
  longer be contradicted by a message substring.

Classification fixes:
- `verify_function` no longer flattens `AgenticRLError` subclasses and timeouts
  into `ValidationError`, which made a failed instance query or a request
  timeout look like a 400. It also stopped discarding the reason the deployed
  function itself reported.
- Add `TimeoutErrorWithCode` deriving from the builtin `TimeoutError`, so a
  wrapped `asyncio.TimeoutError` still reaches the 504 branch on every
  supported Python version. Previously it became a 500 and the
  `sdk.agentic_rl.FunctionTestTimeout` code was unreachable.
- `AgenticRL.init()` wrapped nothing, so a bad `config_path` leaked a raw
  `IOErrorWithCode` with no `status_code` at all. A missing or malformed config
  is the caller's to fix and now reports 400.
- A WebSocket handshake 403 was reported as 401, sending callers to rotate an
  API key that was in fact valid.
- `AgenticRL.run()` logged only after passing `DashScopeException` straight
  through, which left most workflow failures unrecorded.
- The service-unavailable probe matched the bare substring "503", so an address
  such as `10.50.30.1:5030` was misread as an outage.

Detail preservation:
- Transport, WebSocket and `iter_over_async` failures keep the originating
  exception instead of replacing it with a generic 500 message. `httpx`
  timeouts usually carry no message at all, so those fall back to the type name.
- Unparsable SSE bodies report 500 and retain the payload.
- Passing a `requests.Session` to an async call silently ignored it; it now
  warns, since only an `aiohttp.ClientSession` can be reused there.

The log-and-classify sequence duplicated across five `AgenticRL` methods is
extracted into `_log_internal_error` / `_public_exception`, and the resulting
record is attributed to the calling handler rather than to the helper.

Tests: 1132 passed, 6 skipped.

Author: zhansheng.lzs

dashscope/acli/examples/dashscope-sdk-expert/.acli/skills/agent.md

@@ -67,16 +67,21 @@ with client.sessions.events.stream(session.id) as stream:
 | Error code/exception | HTTP status | Meaning | Handling |
 | --- | --- | --- | --- |
 | `InputRequired` / `ModelRequired` / `InvalidInput` | raised locally | missing required params such as app_id/prompt/model | add params per the exception message; Application failures do not raise — check status_code |
-| `invalid_request_error` (InvalidRequestError) | 400 | invalid agentstudio request parameters | check parameter names/types, e.g. empty events raises a local ValueError |
+| `invalid_request_error` / `request_too_large` (InvalidRequestError) | 400/413 | invalid agentstudio request parameters, or payload too large | check parameter names/types, e.g. empty events raises a local ValueError |
 | `authentication_error` (AuthenticationError) | 401 | api_key missing or invalid | check api_key or DASHSCOPE_API_KEY |
-| `permission_denied_error` (PermissionDeniedError) | 403 | no access to the resource | check workspace/uid and resource ownership |
+| `permission_denied_error` / `permission_error` (PermissionDeniedError) | 403 | no access to the resource | check workspace/uid and resource ownership |
 | `not_found_error` (NotFoundError) | 404 | agent/session and other resources do not exist | verify the id and region/workspace are correct |
 | `conflict_error` (ConflictError) | 409 | version in agents.update does not match the server | retrieve the latest version first, then update |
-| `rate_limit_error` (RateLimitError) | 429 | rate limited | retry with backoff (client default max_retries=2) |
-| `api_error` (InternalServerError) / `overloaded_error` (OverloadedError) | 500/502/504 / 503 | server error/overloaded | troubleshoot with `request_id` or retry |
+| `rate_limit_error` / `billing_error` (RateLimitError) | 429 | rate limited or out of quota | retry with backoff (client default max_retries=2) |
+| `api_error` / `timeout_error` (InternalServerError), `overloaded_error` (OverloadedError) | 500/502/504 / 503 | server error/overloaded | troubleshoot with `request_id` or retry |
 | `APITimeoutError` / `APIConnectionError` | no response | connection/read/write timeout | increase timeout, check network, then retry |
 | `StreamError` / `StreamClosedError` | mid-stream | SSE protocol error/stream closed | call `events.stream` again to reopen the stream |
 
+Match on the exception class, not on `.code`: `.code` echoes the server's raw
+string, so a 403 may arrive as either `permission_denied_error` or
+`permission_error`, and it is normalised to `api_error` when the server omits
+it. The class is always the one listed above.
+
 ## Java SDK
 
 Java SDK v2.22.23 entry points:

dashscope/agentstudio/exceptions.py

@@ -10,17 +10,34 @@
         "request_id": "req_..."
     }
 
-The pre-release backend currently emits ``error_code``/``error_message``
-instead of nested ``error.{code,message}``. We accept both shapes and
-normalize to the documented form. The compatibility branch is marked
-with ``# TODO(bma-fix)`` so we can remove it once the backend aligns.
+Codes come from the server response and are preserved as-is on ``.code``.
+When no code is present, :func:`from_response` reports the generic
+``api_error`` rather than inventing a public code from the status number.
+The raw payload stays on ``.raw``.
+
+The exception *type* is resolved separately: a recognized server code wins,
+otherwise the HTTP status picks the class. Callers can therefore keep using
+``except NotFoundError`` while ``.code`` still carries whatever the server
+actually said (including service-specific codes such as
+``bma_invalid_event``).
+
+The pre-release backend emits ``error_code``/``error_message`` instead of
+nested ``error.{code,message}``. Both shapes are accepted; the compatibility
+branches are marked ``# TODO(bma-fix)`` for removal once the backend aligns.
 """
 
 from __future__ import annotations
 
 from typing import Any, Dict, Mapping, Optional
 
 from dashscope.common.error import DashScopeException
+from dashscope.common.error_registry import (
+    SDK_AGENTSTUDIO_API_CONNECTION_ERROR,
+    SDK_AGENTSTUDIO_API_TIMEOUT_ERROR,
+    SDK_AGENTSTUDIO_STREAM_CLOSED_ERROR,
+    SDK_AGENTSTUDIO_STREAM_ERROR,
+    INTERNAL_ERROR,
+)
 
 
 class AgentStudioError(DashScopeException):
@@ -75,13 +92,13 @@ def __repr__(self) -> str:  # pragma: no cover - debug helper
 class APIConnectionError(AgentStudioError):
     """Raised when the HTTP request fails before a response is read."""
 
-    code = "api_connection_error"
+    code = SDK_AGENTSTUDIO_API_CONNECTION_ERROR.name
 
 
 class APITimeoutError(APIConnectionError):
     """Raised on connect / read timeouts."""
 
-    code = "api_timeout_error"
+    code = SDK_AGENTSTUDIO_API_TIMEOUT_ERROR.name
 
 
 # ---------------------------------------------------------------------------
@@ -90,7 +107,12 @@ class APITimeoutError(APIConnectionError):
 
 
 class APIStatusError(AgentStudioError):
-    """Raised when the server returns a non-2xx status."""
+    """Raised when the server returns a non-2xx status.
+
+    Subclasses below give callers a stable type to catch. ``.code`` is always
+    the server's own value, so the class carries no information that the code
+    attribute does not -- it exists for ``except`` clauses.
+    """
 
     code = "api_status_error"
 
@@ -124,7 +146,7 @@ class OverloadedError(APIStatusError):
 
 
 class InternalServerError(APIStatusError):
-    code = "api_error"
+    code = INTERNAL_ERROR.anthropic_error_code
 
 
 # ---------------------------------------------------------------------------
@@ -135,42 +157,49 @@ class InternalServerError(APIStatusError):
 class StreamError(AgentStudioError):
     """Raised when an SSE stream encounters a fatal protocol error."""
 
-    code = "stream_error"
+    code = SDK_AGENTSTUDIO_STREAM_ERROR.name
 
 
 class StreamClosedError(StreamError):
     """Raised when consumers attempt I/O on an already-closed stream."""
 
-    code = "stream_closed"
+    code = SDK_AGENTSTUDIO_STREAM_CLOSED_ERROR.name
 
 
 # ---------------------------------------------------------------------------
 # Dispatcher
 # ---------------------------------------------------------------------------
 
-
 _STATUS_TO_DEFAULT: Dict[int, type] = {
     400: InvalidRequestError,
     401: AuthenticationError,
     403: PermissionDeniedError,
     404: NotFoundError,
     409: ConflictError,
+    413: InvalidRequestError,
     429: RateLimitError,
     500: InternalServerError,
     502: InternalServerError,
     503: OverloadedError,
     504: InternalServerError,
 }
 
+# Covers every anthropic_error_code the error registry can emit, plus the
+# legacy permission_denied_error / conflict_error spellings. Each entry agrees
+# with _STATUS_TO_DEFAULT for the status the registry pairs it with.
 _CODE_TO_CLASS: Dict[str, type] = {
     "invalid_request_error": InvalidRequestError,
     "authentication_error": AuthenticationError,
+    "permission_error": PermissionDeniedError,
     "permission_denied_error": PermissionDeniedError,
     "not_found_error": NotFoundError,
     "conflict_error": ConflictError,
+    "request_too_large": InvalidRequestError,
     "rate_limit_error": RateLimitError,
+    "billing_error": RateLimitError,
     "overloaded_error": OverloadedError,
     "api_error": InternalServerError,
+    "timeout_error": InternalServerError,
 }
 
 
@@ -179,16 +208,21 @@ def from_response(
     status_code: int,
     body: Any,
     headers: Optional[Mapping[str, str]] = None,
-) -> AgentStudioError:
-    """Build an :class:`AgentStudioError` instance from a HTTP response.
+) -> APIStatusError:
+    """Build an :class:`APIStatusError` instance from a HTTP response.
 
-    Accepts both the documented ``{type, error:{code,message}, request_id}``
-    shape and the pre-release ``{type, error:{error_code, error_message}}``
-    shape. Falls back to a Spring default ``{timestamp,status,error,path}``
-    when the body is not JSON-serializable.
+    Accepts the documented ``{type, error:{code,message}, request_id}`` shape,
+    the pre-release ``error:{error_code,error_message}`` shape, the classic
+    flat DashScope ``{code, message, request_id}`` envelope, and falls back to
+    a Spring default ``{timestamp,status,error,path}`` page.
 
     The ``x-request-id`` response header is preferred over the body
     ``request_id`` field (server-generated IDs are more reliable for tracing).
+
+    The server's code is preserved as-is on ``.code``; only when no code is
+    present does it fall back to the generic ``api_error``. The exception
+    class is resolved separately -- a recognized code wins, otherwise the
+    HTTP status decides.
     """
 
     code: Optional[str] = None
@@ -211,30 +245,28 @@ def from_response(
             message = err.get("message") or err.get(
                 "error_message",
             )  # TODO(bma-fix)
-        # Spring default fallback.
-        if (
-            message is None
-            and "error" in body
-            and isinstance(body["error"], str)
-        ):
+        # Spring default fallback. Its ``error`` field is a human phrase
+        # ("Not Found"), so it informs the message but never the code.
+        if message is None and isinstance(body.get("error"), str):
             message = body["error"]
-            code = body.get("error") or "api_error"
+        # Flat DashScope envelope: code/message at the top level.
+        if code is None:
+            code = body.get("code")
         if message is None:
             message = body.get("message")
 
+    # Classify before normalizing: the synthesized generic code below must not
+    # drive classification, or a bodiless 404 would report InternalServerError.
+    cls = _CODE_TO_CLASS.get(code) if code else None
+    if cls is None:
+        cls = _STATUS_TO_DEFAULT.get(status_code, APIStatusError)
+
+    if not code:
+        code = INTERNAL_ERROR.anthropic_error_code
+
     if message is None:
         message = f"HTTP {status_code}"
-    if code is None:
-        code = _STATUS_TO_DEFAULT.get(  # type: ignore[attr-defined]
-            status_code,
-            APIStatusError,
-        ).code
-
-    cls = (
-        _CODE_TO_CLASS.get(code)
-        or _STATUS_TO_DEFAULT.get(status_code)
-        or APIStatusError
-    )
+
     return cls(
         message,
         code=code,

dashscope/agentstudio/transport.py

@@ -204,6 +204,18 @@ def _should_retry_exception(err: BaseException) -> Tuple[bool, Optional[Any]]:
     return False, None
 
 
+def _describe_exception(err: BaseException) -> str:
+    """Render an exception into a message worth showing the caller.
+
+    ``httpx`` timeout exceptions usually carry no message at all, so a bare
+    ``str(err)`` would surface an empty string. Fall back to the type name.
+    """
+    detail = str(err).strip()
+    if detail:
+        return f"{type(err).__name__}: {detail}"
+    return type(err).__name__
+
+
 # ---------------------------------------------------------------------------
 # Header builder (shared by sync + async transports)
 # ---------------------------------------------------------------------------
@@ -220,7 +232,7 @@ def build_headers(
     """Compose the canonical AgentStudio request headers."""
 
     if not api_key:
-        raise exceptions.AuthenticationError(
+        raise exceptions.APIStatusError(
             "api_key is required. Pass it via Client(api_key=...) or "
             "the DASHSCOPE_API_KEY environment variable.",
             code="authentication_error",
@@ -363,14 +375,18 @@ def request(  # pylint: disable=too-many-branches
             except httpx.TimeoutException as exc:
                 last_exc = exc
                 if attempt >= self.max_retries:
-                    raise exceptions.APITimeoutError(str(exc)) from exc
+                    raise exceptions.APITimeoutError(
+                        _describe_exception(exc),
+                    ) from exc
             except Exception as exc:
                 if isinstance(exc, exceptions.AgentStudioError):
                     raise
                 should_retry, _ = _should_retry_exception(exc)
                 last_exc = exc
                 if attempt >= self.max_retries or not should_retry:
-                    raise exceptions.APIConnectionError(str(exc)) from exc
+                    raise exceptions.APIConnectionError(
+                        _describe_exception(exc),
+                    ) from exc
             else:
                 if stream:
                     if resp.status_code >= 400:
@@ -587,14 +603,18 @@ async def request(  # pylint: disable=too-many-branches
             except httpx.TimeoutException as exc:
                 last_exc = exc
                 if attempt >= self.max_retries:
-                    raise exceptions.APITimeoutError(str(exc)) from exc
+                    raise exceptions.APITimeoutError(
+                        _describe_exception(exc),
+                    ) from exc
             except Exception as exc:
                 if isinstance(exc, exceptions.AgentStudioError):
                     raise
                 should_retry, _ = _should_retry_exception(exc)
                 last_exc = exc
                 if attempt >= self.max_retries or not should_retry:
-                    raise exceptions.APIConnectionError(str(exc)) from exc
+                    raise exceptions.APIConnectionError(
+                        _describe_exception(exc),
+                    ) from exc
             else:
                 if stream:
                     if resp.status_code >= 400: