エラーハンドリングリファレンス

English | 中文 | 日本語 | Español | 한국어

これは README のエラーハンドリングの節（DashScopeException を捕捉し、status_code を確認する基本パターン）をさらに掘り下げた内容です。

例外クラス

SDK が送出するすべての例外（dashscope/common/error.py）は DashScopeException を継承しているため、except DashScopeException 一つでそのいずれも捕捉できます。よく使われるものと、実際にどのような場合に送出されるかは次のとおりです：

例外	発生する場合
`InputRequired`	必須の入力が欠けている場合、例：`prompt`/`messages` が指定されていない
`ModelRequired`	`model` 引数が空の場合
`AuthenticationError`	API Key がどこにも（コード、環境変数、ファイル）設定されていない場合
`InvalidInput`	引数の組み合わせが不正な場合、例：矛盾するパラメータの指定
`InvalidFileFormat`	アップロードするファイルが想定フォーマットと一致しない場合（例：ファインチューニング用ファイルが JSONL 形式でない）
`UnsupportedModel`	その操作でリクエストされたモデルがサポートされていない場合（例：ローカルトークナイズが対応していないモデル）
`UploadFileException`	ローカルファイル（例：ビジョン／画像リクエスト用）の OSS へのアップロードに失敗した場合
`UnsupportedDataType`	入力／出力のデータ型が認識できない場合
`TimeoutException`	ブロッキングの待機処理（例：`Runs.wait`）がタイムアウトを超えた場合

from dashscope import Generation
from dashscope.common.error import (
    DashScopeException,
    InputRequired,
    ModelRequired,
    AuthenticationError,
)

try:
    Generation.call(model="", messages=[{"role": "user", "content": "Hi"}])
except ModelRequired as e:
    print(f"Model missing: {e}")
except (InputRequired, AuthenticationError) as e:
    print(f"Invalid setup: {e}")
except DashScopeException as e:
    print(f"Other SDK-side error: {e}")

サポート問い合わせ用の request_id の取得

成功・失敗を問わず、すべてのレスポンスには request_id が含まれます。問題を報告したりサポートに問い合わせたりする際は、これを添えてください：

from http import HTTPStatus
from dashscope import Generation

response = Generation.call(model="qwen-plus", messages=[{"role": "user", "content": "Hi"}])
if response.status_code != HTTPStatus.OK:
    print(f"request_id={response.request_id} code={response.code} message={response.message}")

自動的なコネクション再試行

プールされていたキープアライブ接続がサーバーや途中のロードバランサーによって静かに切断されていた場合（レスポンスのバイトが1つも届く前に接続エラーとして検知された場合）、SDK はそのリクエストを内部で一度だけ自動的に再試行します——同期（requests ベース）・非同期（aiohttp ベース）のどちらのクライアントもこれを内部で行います。この挙動は設定変更できず、利用者側のコードも不要です。あくまで「レスポンスが開始する前に接続が切断された」場合のみをカバーするものであり、レート制限や不正な入力といったアプリケーションレベルの失敗（README のエラーハンドリングの節で説明したパターンで、通常のエラーレスポンスとして返されます）は対象外です。

レート制限に対するリトライとバックオフ

上記のコネクションレベルの再試行とは異なり、SDK はレート制限や一時的なサーバーエラーといったアプリケーションレベルの失敗を自動的には再試行しません ——これらは 200 以外の status_code を持つ通常のレスポンスとして返され、再試行するかどうかはあなたのコード次第です。status_code を見て行うシンプルな指数バックオフの例：

import time
from http import HTTPStatus
from dashscope import Generation

def call_with_backoff(max_retries=5, base_delay=1.0, **kwargs):
    for attempt in range(max_retries):
        response = Generation.call(**kwargs)
        if response.status_code == HTTPStatus.OK:
            return response
        if response.status_code in (429, 500, 502, 503, 504) and attempt < max_retries - 1:
            time.sleep(base_delay * (2 ** attempt))
            continue
        return response  # リトライを諦める：呼び出し側で status_code/code/message を確認する

response = call_with_backoff(model="qwen-plus", messages=[{"role": "user", "content": "Hi"}])

FilesExpand file tree

error-handling_ja.md

Latest commit

History