跳转至内容

错误(Errors)

SDK 的所有异常都继承自 DashScopeError,携带 message、code、 status_code、request_id、body 与 headers。捕获基类即可处理任何 SDK 或 API 失败,也可捕获具体子类做更精细的控制。

基类与错误码

DashScopeError

DashScopeError(
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: DashScopeException

Base class for all dashscope 2.0 SDK errors.

Roots into the shared :class:~dashscope._shared._errors.DashScopeException so a single except DashScopeException catches errors from both the 1.x API classes and the 2.0 client (including the AgentStudio sub-SDK).

Source code in dashscope/errors.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.code = code
    self.status_code = status_code
    self.request_id = request_id
    self.body = body
    self.headers = headers or {}

message instance-attribute

message = message

code instance-attribute

code = code

status_code instance-attribute

status_code = status_code

request_id instance-attribute

request_id = request_id

body instance-attribute

body = body

headers instance-attribute

headers = headers or {}

diagnosis property

diagnosis

Structured local fix guidance, or None if no rule matched.

Matched offline from (status_code, code, message) by the devkit rule table -- no network, no model call. Advisory data only: the SDK never prints it. The CLI renders it, and dashscope.devkit.install_excepthook() appends it to uncaught tracebacks. Imported lazily so the error path stays dependency-free and the devkit package is never loaded on the success path.

ErrorCode

Bases: str, Enum

Server-side error codes returned in response.code.

INVALID_API_KEY class-attribute instance-attribute

INVALID_API_KEY = 'InvalidApiKey'

ACCESS_DENIED class-attribute instance-attribute

ACCESS_DENIED = 'AccessDenied'

ACCESS_DENIED_UNPURCHASED class-attribute instance-attribute

ACCESS_DENIED_UNPURCHASED = 'AccessDenied.Unpurchased'

INVALID_PARAMETER class-attribute instance-attribute

INVALID_PARAMETER = 'InvalidParameter'

MODEL_NOT_EXIST class-attribute instance-attribute

MODEL_NOT_EXIST = 'Model.NotExist'

DATA_INSPECTION_FAILED class-attribute instance-attribute

DATA_INSPECTION_FAILED = 'DataInspectionFailed'

THROTTLING class-attribute instance-attribute

THROTTLING = 'Throttling'

THROTTLING_RATE_QUOTA class-attribute instance-attribute

THROTTLING_RATE_QUOTA = 'Throttling.RateQuota'

THROTTLING_ALLOCATION_QUOTA class-attribute instance-attribute

THROTTLING_ALLOCATION_QUOTA = 'Throttling.AllocationQuota'

INTERNAL_ERROR class-attribute instance-attribute

INTERNAL_ERROR = 'InternalError'

SERVICE_UNAVAILABLE class-attribute instance-attribute

SERVICE_UNAVAILABLE = 'ServiceUnavailable'

GATEWAY_TIMEOUT class-attribute instance-attribute

GATEWAY_TIMEOUT = 'GatewayTimeout'

ARREARAGE class-attribute instance-attribute

ARREARAGE = 'Arrearage'

SdkError

SdkError(
    message: str,
    *,
    code: Optional[str] = None,
    solution: Optional[str] = None,
    allow_retry: bool = False,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: DashScopeError

A failure the SDK reported itself, with no HTTP response behind it.

code is the catalog name (sdk.agentic_rl.OSSUploadError) and solution the fix guidance shipped alongside it. status_code stays None: the catalog gives SDK-side errors no public projection, so inventing a status would add meaning the standard does not carry.

Source code in dashscope/errors.py
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    solution: Optional[str] = None,
    allow_retry: bool = False,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(
        message,
        code=code,
        request_id=request_id,
        body=body,
        headers=headers,
    )
    self.solution = solution
    self.allow_retry = allow_retry

solution instance-attribute

solution = solution

allow_retry instance-attribute

allow_retry = allow_retry

传输与校验错误

APIConnectionError

APIConnectionError(
    message: Optional[str] = None,
    *,
    detail: Optional[str] = None,
    **kwargs: Any
)

Bases: _CatalogSdkError

Network-level failure (connection refused, DNS, TLS...).

Backed by the catalog's sdk.ConnectionError entry: code / solution / allow_retry default from it, so every raise site is catalog-identical without repeating the wiring. Pass detail instead of message to use the entry's message template.

Source code in dashscope/errors.py
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def __init__(
    self,
    message: Optional[str] = None,
    *,
    detail: Optional[str] = None,
    **kwargs: Any,
) -> None:
    entry = _SDK_ERRORS[self._SDK_ERROR_NAME]
    if message is None:
        message = entry.format_message({"detail": detail or ""})
    kwargs.setdefault("code", entry.name)
    kwargs.setdefault("solution", entry.solution)
    kwargs.setdefault("allow_retry", entry.allow_retry)
    super().__init__(message, **kwargs)

APITimeoutError

APITimeoutError(
    message: Optional[str] = None,
    *,
    detail: Optional[str] = None,
    **kwargs: Any
)

Bases: APIConnectionError

Request timed out; backed by the catalog's sdk.Timeout entry.

Source code in dashscope/errors.py
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def __init__(
    self,
    message: Optional[str] = None,
    *,
    detail: Optional[str] = None,
    **kwargs: Any,
) -> None:
    entry = _SDK_ERRORS[self._SDK_ERROR_NAME]
    if message is None:
        message = entry.format_message({"detail": detail or ""})
    kwargs.setdefault("code", entry.name)
    kwargs.setdefault("solution", entry.solution)
    kwargs.setdefault("allow_retry", entry.allow_retry)
    super().__init__(message, **kwargs)

APIResponseValidationError

APIResponseValidationError(
    message: Optional[str] = None,
    *,
    response: Optional[Response] = None,
    body: Any = None,
    cause: Optional[BaseException] = None,
    request_id: Optional[str] = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: DashScopeError

The gateway answered, but its body did not fit the SDK's models.

Distinct from :class:APIStatusError so that except APIStatusError keeps meaning "the service refused or broke": here nothing failed on the wire and the gateway declared no error, the payload simply could not be parsed into the model the resource returns.

Carries response (None for websocket payloads, which have no response), body as received, and cause, the original validation error. status_code stays None even with a response present: that status is the gateway's and it reported success, so repeating it here would read as the reason for the failure. response.status_code still has it.

Deliberately no catalog entry -- _error_registry.py is vendored from a generator this repo does not carry -- so it roots at :class:DashScopeError, not :class:SdkError, whose code and solution would have to name an entry that does not exist.

Source code in dashscope/errors.py
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
def __init__(
    self,
    message: Optional[str] = None,
    *,
    response: Optional[httpx.Response] = None,
    body: Any = None,
    cause: Optional[BaseException] = None,
    request_id: Optional[str] = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    if headers is None and response is not None:
        headers = response.headers
    data = _extract(body)
    super().__init__(
        message or "Response body failed SDK-side validation.",
        request_id=request_id or _request_id(data, headers or {}),
        body=body,
        headers=headers,
    )
    self.response = response
    self.cause = cause

response instance-attribute

response = response

cause instance-attribute

cause = cause

HTTP 状态错误

APIStatusError

APIStatusError(
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: DashScopeError

A failure the gateway declared, on either layer of the model.

Both a non-2xx HTTP status and an HTTP 200 whose body carries a business code land here; the instance's status_code says which one it was.

Source code in dashscope/errors.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.code = code
    self.status_code = status_code
    self.request_id = request_id
    self.body = body
    self.headers = headers or {}

status_code class-attribute instance-attribute

status_code: Optional[int] = None

BadRequestError

BadRequestError(
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: APIStatusError

Source code in dashscope/errors.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.code = code
    self.status_code = status_code
    self.request_id = request_id
    self.body = body
    self.headers = headers or {}

status_code class-attribute instance-attribute

status_code = _CATALOG_STATUS['BadRequestError']

AuthenticationError

AuthenticationError(
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: APIStatusError

Source code in dashscope/errors.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.code = code
    self.status_code = status_code
    self.request_id = request_id
    self.body = body
    self.headers = headers or {}

status_code class-attribute instance-attribute

status_code = _CATALOG_STATUS['AuthenticationError']

PermissionDeniedError

PermissionDeniedError(
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: APIStatusError

Source code in dashscope/errors.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.code = code
    self.status_code = status_code
    self.request_id = request_id
    self.body = body
    self.headers = headers or {}

status_code class-attribute instance-attribute

status_code = _CATALOG_STATUS['PermissionDeniedError']

NotFoundError

NotFoundError(
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: APIStatusError

Source code in dashscope/errors.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.code = code
    self.status_code = status_code
    self.request_id = request_id
    self.body = body
    self.headers = headers or {}

status_code class-attribute instance-attribute

status_code = _CATALOG_STATUS['NotFoundError']

RequestTooLargeError

RequestTooLargeError(
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: APIStatusError

Source code in dashscope/errors.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.code = code
    self.status_code = status_code
    self.request_id = request_id
    self.body = body
    self.headers = headers or {}

status_code class-attribute instance-attribute

status_code = _CATALOG_STATUS['RequestTooLargeError']

RateLimitError

RateLimitError(
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: APIStatusError

Source code in dashscope/errors.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.code = code
    self.status_code = status_code
    self.request_id = request_id
    self.body = body
    self.headers = headers or {}

status_code class-attribute instance-attribute

status_code = _CATALOG_STATUS['RateLimitError']

InternalServerError

InternalServerError(
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: APIStatusError

Source code in dashscope/errors.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.code = code
    self.status_code = status_code
    self.request_id = request_id
    self.body = body
    self.headers = headers or {}

status_code class-attribute instance-attribute

status_code = _CATALOG_STATUS['InternalServerError']

ServiceUnavailableError

ServiceUnavailableError(
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: APIStatusError

Source code in dashscope/errors.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.code = code
    self.status_code = status_code
    self.request_id = request_id
    self.body = body
    self.headers = headers or {}

status_code class-attribute instance-attribute

status_code = _CATALOG_STATUS['ServiceUnavailableError']

GatewayTimeoutError

GatewayTimeoutError(
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: APIStatusError

Source code in dashscope/errors.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.code = code
    self.status_code = status_code
    self.request_id = request_id
    self.body = body
    self.headers = headers or {}

status_code class-attribute instance-attribute

status_code = _CATALOG_STATUS['GatewayTimeoutError']

ContentFilterError

ContentFilterError(
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None
)

Bases: BadRequestError

Input or output blocked by content moderation.

The catalog entry behind it (content_policy_violation) names BadRequestError; V2 refines that into a dedicated class so moderation blocks are catchable on their own. Subclassing is what keeps the refinement catalog-legal, an invariant the tests pin for every row of the crosswalk.

Source code in dashscope/errors.py
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    message: str,
    *,
    code: Optional[str] = None,
    status_code: Optional[int] = None,
    request_id: Optional[str] = None,
    body: Any = None,
    headers: Optional[Mapping[str, str]] = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.code = code
    self.status_code = status_code
    self.request_id = request_id
    self.body = body
    self.headers = headers or {}

WebSocket 错误

WsEventError

WsEventError(
    message: Optional[str] = None,
    *,
    detail: Optional[str] = None,
    **kwargs: Any
)

Bases: _CatalogSdkError

The server sent an unexpected websocket protocol event.

Backed by the catalog's sdk.ws.ProtocolError entry: code / solution / allow_retry default from it. Pass detail instead of message to use the entry's message template.

Source code in dashscope/errors.py
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def __init__(
    self,
    message: Optional[str] = None,
    *,
    detail: Optional[str] = None,
    **kwargs: Any,
) -> None:
    entry = _SDK_ERRORS[self._SDK_ERROR_NAME]
    if message is None:
        message = entry.format_message({"detail": detail or ""})
    kwargs.setdefault("code", entry.name)
    kwargs.setdefault("solution", entry.solution)
    kwargs.setdefault("allow_retry", entry.allow_retry)
    super().__init__(message, **kwargs)

WsStateError

WsStateError(
    message: Optional[str] = None,
    *,
    detail: Optional[str] = None,
    **kwargs: Any
)

Bases: _CatalogSdkError

Operation invalid for the websocket task's current state.

Backed by the catalog's sdk.ws.IllegalState entry: duplicate start, send after close, receive on a closed session.

Source code in dashscope/errors.py
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def __init__(
    self,
    message: Optional[str] = None,
    *,
    detail: Optional[str] = None,
    **kwargs: Any,
) -> None:
    entry = _SDK_ERRORS[self._SDK_ERROR_NAME]
    if message is None:
        message = entry.format_message({"detail": detail or ""})
    kwargs.setdefault("code", entry.name)
    kwargs.setdefault("solution", entry.solution)
    kwargs.setdefault("allow_retry", entry.allow_retry)
    super().__init__(message, **kwargs)

WsQueueCapacityExceededError

WsQueueCapacityExceededError(
    message: Optional[str] = None,
    *,
    detail: Optional[str] = None,
    **kwargs: Any
)

Bases: _CatalogSdkError

A bounded websocket task receive queue overflowed.

Backed by the catalog's sdk.ws.QueueCapacityExceeded entry.

Source code in dashscope/errors.py
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def __init__(
    self,
    message: Optional[str] = None,
    *,
    detail: Optional[str] = None,
    **kwargs: Any,
) -> None:
    entry = _SDK_ERRORS[self._SDK_ERROR_NAME]
    if message is None:
        message = entry.format_message({"detail": detail or ""})
    kwargs.setdefault("code", entry.name)
    kwargs.setdefault("solution", entry.solution)
    kwargs.setdefault("allow_retry", entry.allow_retry)
    super().__init__(message, **kwargs)

WsBinaryOwnerConflictError

WsBinaryOwnerConflictError(
    message: Optional[str] = None,
    *,
    detail: Optional[str] = None,
    **kwargs: Any
)

Bases: _CatalogSdkError

A shared connection allows one binary owner per direction.

Backed by the catalog's sdk.ws.BinaryOwnerConflict entry.

Source code in dashscope/errors.py
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def __init__(
    self,
    message: Optional[str] = None,
    *,
    detail: Optional[str] = None,
    **kwargs: Any,
) -> None:
    entry = _SDK_ERRORS[self._SDK_ERROR_NAME]
    if message is None:
        message = entry.format_message({"detail": detail or ""})
    kwargs.setdefault("code", entry.name)
    kwargs.setdefault("solution", entry.solution)
    kwargs.setdefault("allow_retry", entry.allow_retry)
    super().__init__(message, **kwargs)