Qoder Agent SDK は、タスクの失敗、SDK の失敗、プロセスの終了を別々に通知します。すべての失敗を例外として扱わず、利用できる最も具体的なシグナルを処理してください。
Result メッセージの数値
将来のランタイムで Result subtype が追加される可能性があります。未知の subtype と
どちらの SDK も Result オブジェクトに任意の数値
現在の qodercli ランタイムは、次の数値コードを正規化し、どちらの SDK でも
SDK 例外は、アプリケーションがセッションを設定、開始、制御、または継続できなかったことを示します。Agent の失敗 Result とは別です。
両方の SDK で共通する機械可読な認証設定コードは次のとおりです。
起動後に認証情報の期限切れが判明した場合は、
SDK を使用するアプリケーションは、通常、プロセス終了コードで分岐せず、Result と SDK 例外を処理します。終了コードは主に Transport の診断、または SDK 外で qodercli を直接起動する場合に使用します。
その他の終了コードやシグナルは、OS、カスタムランタイム、子プロセスから発生する場合があります。TypeScript は
障害調査に役立つ情報として、次を保持します。
error_code と qodercli プロセスの終了コードは、別の番号体系です。一方の値をもう一方の表と照合しないでください。
推奨する処理順序
- SDK が
resultを返すか、例外を送出するまでメッセージを処理します。 - Result では、最初に
subtypeとis_errorを確認します。error_codeが存在する場合のみ、より具体的な復旧処理の選択に使用します。 - メッセージ反復全体を囲んで SDK 例外を捕捉します。例外クラスとフィールドから、設定、ランタイム、Transport の問題を診断します。
- セッション ID、Result subtype、エラーコード、例外名を記録します。認証情報やソースコード全体は、デフォルトでは記録しないでください。
Result subtype
subtype | 意味 | 推奨する対応 |
|---|---|---|
success | Agent がターンを完了した | result を読み、セッションを続けるか閉じる |
error_during_execution | 実行、モデル、サービス、認証、または回復不能なツールエラーで停止した | errors を確認し、利用可能なら error_code を使う。一時的な原因だけを再試行する |
error_max_turns | 設定された最大ターン数に達した | ループやブロックされたツールを確認し、さらにターンが必要な場合だけ上限を増やす |
errors を記録するフォールバック分岐を用意し、この表がすべてを網羅すると仮定しないでください。
Result を処理する
どちらの SDK も Result オブジェクトに任意の数値 error_code を公開します。TypeScript では SDKResultMessage、Python では ResultMessage です。フィールドが存在する場合に使用し、ユーザー向けエラーテキストを解析してコードを取り出さないでください。
Result エラーコード
現在の qodercli ランタイムは、次の数値コードを正規化し、どちらの SDK でも message.error_code で返すことがあります。このフィールドは任意です。また、qodercli は表にない数値サービスコードをそのまま返すことがあります。未知の値はログに残し、subtype と errors をフォールバックとして使用してください。
認証とクォータ
| コード | 意味 | 推奨する対応 |
|---|---|---|
105 | ログインまたは Access Token の期限切れ | 有効な認証情報を取得して新しいセッションを作成し、認証期限切れコールバックを登録する |
110 | 1 日の使用量上限に到達 | 使用期間のリセットを待つか、アカウント上限を確認する |
113 | 使用クォータを消費済み | クォータとプランを確認し、条件を変えずにすぐ再試行しない |
114 | 無料トライアルアカウントの上限に到達 | アカウントの利用資格またはアップグレードを確認する |
115 | 無料ユーザーのクォータに到達 | クォータの更新を待つか、アップグレードを確認する |
116 | チーム管理者の Credits を消費済み | チーム管理者が Credits を補充または調整する |
117 | チームメンバーの Credits を消費済み | チーム管理者に Credits の割り当てまたは補充を依頼する |
118 | 個人の Credits を消費済み | Credits を補充するか、利用可能なアカウントを使用する |
119 | 選択したモデルの無料使用上限に到達 | 利用可能なモデルへ切り替えるか、更新を待つか、プランを確認する |
122 | Billing Group の Credits 上限に到達 | 請求管理者にグループ上限の確認を依頼する |
リクエストとポリシー
| コード | 意味 | 推奨する対応 |
|---|---|---|
406 | 機密コンテンツまたはモデルの拒否によりリクエストがブロックされた | タスクまたは入力を変更し、同じ内容を再試行しない |
416 | 要求した範囲またはリクエスト形式を満たせない | errors を確認し、要求範囲を縮小または修正する |
430 | 要求した機能がサポートされていない | 互換性のある SDK/qodercli へ更新するか、サポートされる機能を使用する |
47902 | Agent の最大ターン数に到達 | 上限を増やす前に、ループ、権限、ツール障害を確認する |
48716 | Hook が Agent の実行をブロックした | 対象 Hook の判断を確認し、Hook またはタスクを修正する |
80411 | 入力コンテンツが長すぎる | プロンプト、添付ファイル、保持するコンテキストを減らす |
80412 | 画像または文書が多すぎる | メディア添付の数を減らして再試行する |
サービスとモデルランタイム
| コード | 意味 | 推奨する対応 |
|---|---|---|
500 | リクエストまたはネットワーク障害 | 接続を確認し、回数を制限した指数バックオフで再試行する |
10408 | リクエストのタイムアウト | バックオフして再試行し、繰り返す場合はタスクを小さくする |
10500 | モデルサービスの内部エラー | 後から再試行し、サポートへの問い合わせではセッション ID を残す |
10605 | モデルリクエストがキュー待ち | qodercli は通常待機して再試行する。Result に届いた場合は後から再試行する |
100400 | カスタムモデルサービスのエラー | カスタム Provider の Endpoint とサービス状態を確認する |
100401 | カスタムモデルの認証失敗 | カスタム Provider の認証情報を更新または修正する |
100403 | カスタムモデルが利用不可またはアクセス禁止 | モデルのアクセス権と Provider 設定を確認するか、別のモデルを選択する |
SDK 例外
SDK 例外は、アプリケーションがセッションを設定、開始、制御、または継続できなかったことを示します。Agent の失敗 Result とは別です。
| 状況 | TypeScript | Python | 重要なフィールド |
|---|---|---|---|
| 認証が未設定 | code: "auth_not_configured" を持つ Error | code: "auth_not_configured" を持つ Error | code |
| PAT 環境変数がない | AuthAccessTokenEnvVarError | AuthAccessTokenEnvVarError | code |
| Service Account 環境変数がない | AuthServiceAccountEnvVarError | AuthServiceAccountEnvVarError | code |
| qodercli が見つからない、または起動できない | QoderCliProcessError | CLINotFoundError / CLIConnectionError | メッセージ、TypeScript の stderr、Python のパス/メッセージ |
| qodercli が予期せず終了した | QoderCliProcessError | ProcessError | exitCode / exit_code、stderr、TypeScript の signal |
| モデル選択コールバックのタイムアウト | ModelPolicyTimeoutError | ModelPolicyTimeoutError | timeoutMs / timeout_ms |
| プロトコルバージョンの不一致 | ProtocolVersionMismatchError | ProtocolVersionMismatchError | CLI と SDK のプロトコルバージョン |
| ランタイムに必要な機能がない | UnsupportedCliCapabilityError | UnsupportedCliCapabilityError | capability |
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 | キャンセルまたは割り込み |
QoderCliProcessError.exitCode と .signal、Python は ProcessError.exit_code で利用可能な終了コードを公開します。
ログとサポート
障害調査に役立つ情報として、次を保持します。
- SDK の言語とバージョン
- 利用できる場合は
system/initメッセージの qodercli バージョン session_id、Resultsubtype、任意のerror_code、errors- 例外クラス、機械可読な
code、プロセス終了コード、シグナル - 初期化前、ツール呼び出し中、Result の後のどこで失敗したか
次のステップ
- SDK 認証 — 認証情報の設定と期限切れの処理
- 権限 — ツールの拒否と承認動作の理解
- Hooks — Hook による実行ブロックの診断
- セッション制御 — 実行中セッションの中断と管理
- SDK References — TypeScript と Python の正確な型の確認