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 では、最初に subtypeis_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 を処理する

どちらの SDK も Result オブジェクトに任意の数値 error_code を公開します。TypeScript では SDKResultMessage、Python では ResultMessage です。フィールドが存在する場合に使用し、ユーザー向けエラーテキストを解析してコードを取り出さないでください。
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: message.errors,
      sessionId: message.session_id,
    });

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

Result エラーコード

現在の qodercli ランタイムは、次の数値コードを正規化し、どちらの SDK でも message.error_code で返すことがあります。このフィールドは任意です。また、qodercli は表にない数値サービスコードをそのまま返すことがあります。未知の値はログに残し、subtypeerrors をフォールバックとして使用してください。

認証とクォータ

コード意味推奨する対応
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 に届いた場合は後から再試行する
100400カスタムモデルサービスのエラーカスタム Provider の Endpoint とサービス状態を確認する
100401カスタムモデルの認証失敗カスタム Provider の認証情報を更新または修正する
100403カスタムモデルが利用不可またはアクセス禁止モデルのアクセス権と Provider 設定を確認するか、別のモデルを選択する
一時的であると確認できるエラーだけを再試行してください。最大試行回数、指数バックオフ、ジッターを設定します。認証、クォータ、ポリシー、入力、設定のエラーは、条件を変更してから再実行する必要があります。

SDK 例外

SDK 例外は、アプリケーションがセッションを設定、開始、制御、または継続できなかったことを示します。Agent の失敗 Result とは別です。
状況TypeScriptPython重要なフィールド
認証が未設定code: "auth_not_configured" を持つ Errorcode: "auth_not_configured" を持つ Errorcode
PAT 環境変数がないAuthAccessTokenEnvVarErrorAuthAccessTokenEnvVarErrorcode
Service Account 環境変数がないAuthServiceAccountEnvVarErrorAuthServiceAccountEnvVarErrorcode
qodercli が見つからない、または起動できないQoderCliProcessErrorCLINotFoundError / CLIConnectionErrorメッセージ、TypeScript の stderr、Python のパス/メッセージ
qodercli が予期せず終了したQoderCliProcessErrorProcessErrorexitCode / exit_codestderr、TypeScript の signal
モデル選択コールバックのタイムアウトModelPolicyTimeoutErrorModelPolicyTimeoutErrortimeoutMs / timeout_ms
プロトコルバージョンの不一致ProtocolVersionMismatchErrorProtocolVersionMismatchErrorCLI と SDK のプロトコルバージョン
ランタイムに必要な機能がないUnsupportedCliCapabilityErrorUnsupportedCliCapabilityErrorcapability
両方の 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 を使用し、有効な認証情報で新しいセッションを作成してください。SDK 認証を参照してください。

qodercli プロセス終了コード

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

ログとサポート

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

次のステップ

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