Skip to main content
リファレンス

エラー処理とエラーコード

Qoder Agent SDK は、タスクの失敗、SDK の失敗、プロセスの終了を別々に通知します。すべての失敗を例外として扱わず、利用できる最も具体的なシグナルを処理してください。
どこで失敗したか?
   |
   +-- Agent はタスクを終了したが、成功しなかった
   |      `result` メッセージ:subtype、errors、任意の error_code
   |
   +-- SDK がセッションを開始または維持できなかった
   |      送出された例外:クラス、code、診断フィールド
   |
   `-- qodercli プロセスが停止した
          プロセス終了コード:Transport レベルの診断情報
Result メッセージの error_code と qodercli プロセスの終了コードは、別の番号体系です。一方の値をもう一方の表と照合しないでください。

推奨する処理順序

  1. SDK が result を返すか、例外を送出するまでメッセージを処理します。
  2. Result では、最初に subtype と is_error を確認します。error_code が存在する場合のみ、より具体的な復旧処理の選択に使用します。
  3. メッセージ反復全体を囲んで SDK 例外を捕捉します。例外クラスとフィールドから、設定、ランタイム、Transport の問題を診断します。
  4. セッション ID、Result subtype、エラーコード、例外名を記録します。認証情報やソースコード全体は、デフォルトでは記録しないでください。
失敗した Result と、その後のプロセス例外が同じセッション障害を表す場合があります。診断用に両方を記録しても、1 回の障害についてユーザーへ 2 回通知しないようにしてください。

Result subtype

subtype意味推奨する対応
successAgent がターンを完了したresult を読み、セッションを続けるか閉じる
error_during_execution実行、モデル、サービス、認証、または回復不能なツールエラーで停止したerrors を確認し、利用可能なら error_code を使う。一時的な原因だけを再試行する
error_max_turns設定された最大ターン数に達したループやブロックされたツールを確認し、さらにターンが必要な場合だけ上限を増やす
将来のランタイムで Result subtype が追加される可能性があります。未知の subtype と errors を記録するフォールバック分岐を用意し、この表がすべてを網羅すると仮定しないでください。

Result を処理する

TypeScript の SDKResultMessage.error_code は任意の number | string、Python の ResultMessage は任意の数値コードを公開します。TypeScript は CLI が返した storage_insufficient などの文字列コードや未知のコードをそのまま保持します。フィールドが存在する場合に使用し、ユーザー向けエラーテキストを解析してコードを取り出さないでください。 Java の ResultMessage にはエラーコードのフィールドがありません。outcome() は正規化した結果 SUCCESS、ERROR、UNKNOWN を返し、wireSubtype()、wireIsError()、errors() はそれぞれ subtype、is_error、errors に対応します。error_code が必要な場合は rawJson() から読み取ります。
import {
  QoderCliProcessError,
  accessTokenFromEnv,
  query,
} from '@qoder-ai/qoder-agent-sdk';

let resultReceived = false;

try {
  for await (const message of query({
    prompt: 'テストスイートを実行し、失敗した項目を説明してください。',
    options: { auth: accessTokenFromEnv() },
  })) {
    if (message.type !== 'result') continue;

    resultReceived = true;
    if (message.subtype === 'success' && !message.is_error) {
      console.log(message.result);
      continue;
    }

    console.error({
      subtype: message.subtype,
      errorCode: message.error_code,
      errors: 'errors' in message ? message.errors : [message.result],
      sessionId: message.session_id,
    });

    if (message.error_code === 105) {
      // 新しい認証情報を取得し、新しい SDK セッションを作成します。
    } else if (
      typeof message.error_code === 'number' &&
      [500, 10408, 10500].includes(message.error_code)
    ) {
      // 回数を制限した指数バックオフで後から再試行します。
    }
  }
} catch (error) {
  if (error instanceof QoderCliProcessError) {
    console.error({
      exitCode: error.exitCode,
      signal: error.signal,
      stderr: error.stderr,
      resultReceived,
    });
  } else {
    throw error;
  }
}

Result エラーコード

現在の qodercli ランタイムは、次の数値コードを正規化し、TypeScript と Python の SDK では message.error_code で返すことがあります。Java では ResultMessage.rawJson() の error_code フィールドから読み取ります。このフィールドは任意です。また、qodercli は表にない数値サービスコードをそのまま返すことがあります。未知の値はログに残し、subtype と errors をフォールバックとして使用してください。

認証とクォータ

コード意味推奨する対応
105ログインまたは Access Token の期限切れ有効な認証情報を取得して新しいセッションを作成し、認証期限切れコールバックを登録する
1101 日の使用量上限に到達使用期間のリセットを待つか、アカウント上限を確認する
113使用クォータを消費済みクォータとプランを確認し、条件を変えずにすぐ再試行しない
114無料トライアルアカウントの上限に到達アカウントの利用資格またはアップグレードを確認する
115無料ユーザーのクォータに到達クォータの更新を待つか、アップグレードを確認する
116チーム管理者の Credits を消費済みチーム管理者が Credits を補充または調整する
117チームメンバーの Credits を消費済みチーム管理者に Credits の割り当てまたは補充を依頼する
118個人の Credits を消費済みCredits を補充するか、利用可能なアカウントを使用する
119選択したモデルの無料使用上限に到達利用可能なモデルへ切り替えるか、更新を待つか、プランを確認する
122Billing Group の Credits 上限に到達請求管理者にグループ上限の確認を依頼する

リクエストとポリシー

コード意味推奨する対応
406機密コンテンツまたはモデルの拒否によりリクエストがブロックされたタスクまたは入力を変更し、同じ内容を再試行しない
416要求した範囲またはリクエスト形式を満たせないerrors を確認し、要求範囲を縮小または修正する
430要求した機能がサポートされていない互換性のある SDK/qodercli へ更新するか、サポートされる機能を使用する
47902Agent の最大ターン数に到達上限を増やす前に、ループ、権限、ツール障害を確認する
48716Hook が Agent の実行をブロックした対象 Hook の判断を確認し、Hook またはタスクを修正する
80411入力コンテンツが長すぎるプロンプト、添付ファイル、保持するコンテキストを減らす
80412画像または文書が多すぎるメディア添付の数を減らして再試行する

サービスとモデルランタイム

コード意味推奨する対応
500リクエストまたはネットワーク障害接続を確認し、回数を制限した指数バックオフで再試行する
10408リクエストのタイムアウトバックオフして再試行し、繰り返す場合はタスクを小さくする
10500モデルサービスの内部エラー後から再試行し、サポートへの問い合わせではセッション ID を残す
10605モデルリクエストがキュー待ちqodercli は通常待機して再試行する。Result に届いた場合は後から再試行する
一時的であると確認できるエラーだけを再試行してください。最大試行回数、指数バックオフ、ジッターを設定します。認証、クォータ、ポリシー、入力、設定のエラーは、条件を変更してから再実行する必要があります。

SDK 例外

SDK 例外は、アプリケーションがセッションを設定、開始、制御、または継続できなかったことを示します。Agent の失敗 Result とは別です。
状況TypeScriptPythonJava重要なフィールド
認証が未設定code: "auth_not_configured" を持つ Errorcode: "auth_not_configured" を持つ ErrorInvalidOptionsExceptioncode、Java の getCode()
PAT 環境変数がないAuthAccessTokenEnvVarErrorAuthAccessTokenEnvVarErrorAuthenticationExceptioncode、Java の getCode()
Service Account 環境変数がないAuthServiceAccountEnvVarErrorAuthServiceAccountEnvVarError—code
qodercli が見つからない、または起動できないQoderCliProcessErrorCLINotFoundError / CLIConnectionErrorCliNotFoundException、RuntimeInstallException、またはエラーコード CLI_START_FAILED の QoderExceptionメッセージ、TypeScript の stderr、Python のパス/メッセージ、Java の getCode()
qodercli が予期せず終了したQoderCliProcessErrorProcessErrorCliProcessException。終了コード 41 の場合は AuthenticationExceptionexitCode / exit_code、stderr、TypeScript の signal、Java の getExitCode()、getStderrTail()
モデル選択コールバックのタイムアウトModelPolicyTimeoutErrorModelPolicyTimeoutError例外を投げない。表の後の説明を参照timeoutMs / timeout_ms
プロトコルバージョンの不一致ProtocolVersionMismatchErrorProtocolVersionMismatchErrorProtocolVersionMismatchExceptionCLI と SDK のプロトコルバージョン
ランタイムに必要な機能がないUnsupportedCliCapabilityErrorUnsupportedCliCapabilityErrorUnsupportedCliCapabilityExceptioncapability、Java の capabilityState()
初期化完了前に CLI が失敗 Result を返すQoderCliInitializationError——message、code、result
Java のモデル選択コールバックのタイムアウトは例外としてアプリケーションに渡されないため、catch では捕捉できません。SDK はエラーコード MODEL_RESOLUTION_TIMEOUT を CLI に返し、診断リスナーに inbound_control_request_failed イベントを送ります。その detail には error=MODEL_RESOLUTION_TIMEOUT が含まれます。このケースを検出するには DiagnosticsListener を登録し、このターンの結果は ResultMessage.outcome() で処理して、ERROR の場合は errors() を読み取ってください。 TypeScript の startup() と query.initializationResult() は、初期化完了前に CLI が失敗 Result を返すと QoderCliInitializationError を送出します。message は CLI のエラーテキスト、code は任意の数値または文字列の error_code、result は元の Result を保持します。キャンセルは AbortError として扱われます。初期化完了後の失敗は引き続き Result メッセージとして返されます。 TypeScript と Python の SDK で共通する機械可読な認証設定コードは次のとおりです。
code意味
auth_not_configured認証方式が指定されていない
auth_access_token_env_var_not_configured設定した PAT 環境変数が存在しない
auth_service_account_env_var_not_configured設定した Service Account 環境変数が存在しない
起動後に認証情報の期限切れが判明した場合は、onAuthExpired / on_auth_expired を使用し、有効な認証情報で新しいセッションを作成してください。Java にはこのコールバックがないため、AuthenticationException として処理します。SDK 認証を参照してください。

例外とエラーコード(Java)

Java SDK 独自の例外はすべて非検査例外の QoderException を継承しており、getCode() で安定したエラーコードを取得できます。引数エラーと設定エラーは呼び出し時に同期的に投げられます。たとえば build() の検証に失敗すると InvalidOptionsException が投げられます。起動時と実行中の失敗は、メッセージカーソルの hasNext() / next()、consume() が返す stage、その他の非同期メソッドが返す stage から通知されます。join() で待機すると CompletionException に包まれるため、getCause() で元の例外を取り出します。 SDK は自動で再試行せず、組み込み例外の isRetryable() はすべて false を返します。よくあるエラーコードの扱い方は次のとおりです。
エラーコード対処
INVALID_OPTIONS設定を修正する。再試行しても意味はない
AUTHENTICATION_FAILED、CLI_AUTH_FATAL認証情報またはアカウントの権限を修正してから、新しいクエリまたはセッションを作成する
CLI_NOT_FOUND、RUNTIME_INSTALL_FAILED、CLI_START_FAILED、UNSUPPORTED_SECURE_SECRET_TRANSPORTCLI のパス、マネージド CLI のダウンロード、起動環境を確認する。トラブルシューティングを参照
CLI_PROCESS_FAILEDgetExitCode() と getStderrTail() を記録する
UNSUPPORTED_CLI_CAPABILITY現在の CLI は呼び出した機能をサポートしていない。CLI を自分で指定している場合は SDK がマネージドする固定バージョンに切り替え、そうでなければその機能を使わない
SESSION_CLOSEDリソースは閉じられている。呼び出しをやめ、必要なら新しいセッションを作成する
MESSAGE_STREAM_ALREADY_CONSUMED各メッセージストリームは 1 回しか消費できない。openCursor() と consume() は合わせて 1 回しか呼べない
SPOOL_CAPACITY_EXCEEDED未消費のメッセージがバッファの上限を超えた。メッセージストリームを速やかに読み取る
次のエラーコードはセッションが終了したことを示します:QUERY_WRITE_FAILED(単発クエリの入力が CLI に書き込まれなかった)、CONTROL_WRITE_FAILED(制御リクエストまたはレスポンスが CLI に書き込まれなかった)、TURN_ACCOUNTING_FAILED(ターンの状態をこれ以上処理できない)、MESSAGE_DELIVERY_FAILED(バッファ内のメッセージをデコードできなかった)。元のセッションは使い続けられません。ハンドルを閉じ、getCause() で原因を記録してください。会話を続ける場合は、元のセッション ID で SessionOptions.Builder.resume(String) を使って新しいセッションを作成します。 MessageCursor.hasNext() または next() でブロックしているスレッドが割り込まれると ConsumerInterruptedException が投げられ、スレッドの割り込みフラグはセットされたままになります。読み取りをやめる場合はカーソルを閉じます。
Java
try {
    while (cursor.hasNext()) {
        handle(cursor.next());
    }
} catch (ConsumerInterruptedException e) {
    // The interrupt flag is still set; stop reading and release the session.
    cursor.close();
}
カーソルを閉じると、所属するクエリまたはセッションが非同期に閉じられます。例外とエラーコードの一覧は Java 例外一覧を参照してください。

qodercli プロセス終了コード

SDK を使用するアプリケーションは、通常、プロセス終了コードで分岐せず、Result と SDK 例外を処理します。終了コードは主に Transport の診断、または SDK 外で qodercli を直接起動する場合に使用します。
終了コード意味
0プロセスの正常終了
1一般または未分類の失敗
41認証失敗。設定されている場合、SDK は認証期限切れコールバックも呼び出す。Java ではエラーコード CLI_AUTH_FATAL の AuthenticationException として報告される
42無効な入力またはコマンドライン引数
44致命的なサンドボックスエラー
52致命的な設定エラー
53致命的なターン上限エラー
54致命的なツール実行エラー
130キャンセルまたは割り込み
その他の終了コードやシグナルは、OS、カスタムランタイム、子プロセスから発生する場合があります。TypeScript は QoderCliProcessError.exitCode と .signal、Python は ProcessError.exit_code で利用可能な終了コードを公開し、Java は CliProcessException.getExitCode() で公開します。

ログとサポート

障害調査に役立つ情報として、次を保持します。
  • SDK の言語とバージョン
  • 利用できる場合は system/init メッセージの qodercli バージョン
  • session_id、Result subtype、任意の error_code、errors
  • 例外クラス、機械可読な code、プロセス終了コード、シグナル
  • 初期化前、ツール呼び出し中、Result の後のどこで失敗したか
承認された診断手順で明示的に必要とされない限り、PAT、Service Account Key、Authorization Header、プロンプト全体、ソースファイル、ツール出力はマスキングしてください。

次のステップ

  • SDK 認証 — 認証情報の設定と期限切れの処理
  • 権限 — ツールの拒否と承認動作の理解
  • Hooks — Hook による実行ブロックの診断
  • セッション制御 — 実行中セッションの中断と管理
  • SDK References — 各言語の正確な型の確認