インストールから接続確認まで、使い方ガイドに沿って進めましょう。接続できているのにログイン、チャット、APIに問題がある場合は、このガイドの目次から該当箇所を確認してください。ネットワーク経路、サービスの利用条件、利用枠を分けて説明し、異なる問題をひとまとめにしません。
// ACCESS CHECK
AIアクセスの切り分け:ネットワーク・アカウント・機能
最後に成功した操作を特定する
ブラウザーでサービスのトップページが開いても、そのページに必要なリソースの一部が読み込めたと分かるだけです。ログインには別の認証サービス、チャットには独立したAPI、添付ファイルには専用のアップロードサービスが使われる場合があります。トップページは表示されるのにログインできない場合と、ログインできてもメッセージを送れない場合では、問題の箇所が異なります。最後に成功した操作を記録してください。ログイン画面を開いた、サービス画面に戻った、モデルを選択した、回答を受け取った、のどこまで進めたかを確認します。次のテストはその境目から始め、すでに正常な手順を繰り返す必要はありません。
まず、端末の基本的な状態を確認します。同じ端末で普段使うサイトにアクセスできるか、日時とタイムゾーンが正しく設定されているか、現在のネットワークで接続認証が必要かを確認してください。特定のネットワークだけでサービスのページが開かない場合は、名前解決、ゲートウェイ、接続経路を調べます。利用が認められた別のネットワークでも同じアカウント通知が表示される場合は、通知の内容を保存し、アカウントの問題を優先して確認してください。一度ページを更新できただけでは解決と判断せず、最初に失敗した操作をもう一度行い、正常に完了することを確かめます。
接続元の情報とサービスの利用条件は分けて確認する
サービスから見える接続元アドレスは、リクエストがネットワークの出口を通過した後のものです。同じ端末でも、ブラウザー、ターミナル、デスクトップアプリで異なる出口を使うことがあります。また、サービスが判定するアドレスの所在は、公開情報を使った検索結果と一致するとは限りません。接続元アドレスはリスク判定の材料の一つですが、アカウントの所属、ワークスペースのポリシー、支払い情報、サービス自体の提供地域に代わるものではありません。現在地、アカウントの種類、機能が対象外と明示された場合は、サービスの案内に従ってください。回線を選ぶことで利用資格を得られるわけではありません。
ログイン時のリスク判定は、接続元アドレスだけで決まるものではありません。サービスから本人確認を求められたり、セッションに異常があると判断されて手続きが中断されたりする場合もあります。出張後に確認を求められたら、サービスのアカウントセキュリティページで対応が必要な通知がないか確認してください。セキュリティに関する案内がなく、長いリクエストを送信したときだけ切断される場合は、生成中の挙動を調べます。エラーがサービス画面、ブラウザー、企業のゲートウェイ、クライアントのどこから表示されているかを切り分け、一般的な「接続に失敗しました」という表示だけでアカウント制限と判断しないようにしましょう。
比較できる記録を残す
トラブルの記録には、発生時刻とタイムゾーン、ツールとアクセス方法、操作の段階、エラーの種類と詳細、再現性を含めます。開発者ツールでリクエストがキャンセルされた場合は、ページ移動によるものか、アプリが中止したのか、接続が途中で切れたのかも確認してください。「キャンセル」という表示だけでは、サーバーがリクエストを拒否したとは限りません。比較時はアカウント、機能、入力を同じにし、変更する条件は一つだけにします。たとえば、現在のブラウザーで失敗を記録してから、利用が認められたネットワークでも同じ操作を試します。ブラウザー、回線、アカウントを同時に切り替えるのは避けてください。
// PRODUCT SCOPE
プラットフォームの違い:ウェブ・API・ワークスペース
ブランド名ではなく、利用する製品の入口で確認する
同じブランドでも、ウェブ、モバイルアプリ、開発者コンソール、組織向けサービスで、認証情報、権限、利用開始の条件が異なる場合があります。地域について確認するときは、利用中の入口に対応する利用条件を公式ヘルプで調べ、個人アカウント向けか組織アカウント向けかも確認してください。対象地域の一覧が更新される場合は、公式サイトの最新情報を参照します。別の製品で使えた画面を根拠に、現在の入口も利用できると判断しないでください。同じアカウントで複数のページにログインできても、すべての機能が有効とは限りません。
| ツール | まず確認する入口 | 次に確認する条件 |
|---|---|---|
| ChatGPT | チャット画面または開発者向けAPI | アカウントの種類、ワークスペース、プロジェクト |
| Claude | チャットサービスまたは開発者コンソール | 利用する入口の対象地域と権限 |
| Gemini | アプリ、開発者ツール、クラウドプロジェクト | アカウントの管理方法と利用する機能 |
| Copilot | どのCopilot製品かを特定する | 製品ライセンスと所属組織のポリシー |
| Midjourney | ウェブまたは公式にサポートされている利用方法 | アカウント連携、タスク、生成物の状態 |
| Cursor | エディターへのログインまたはエディターからのモデルリクエスト | 選択したモデル、ワークスペース、リクエスト経路 |
チャット用アカウントと開発者プロジェクトを別々に確認する
ChatGPTやClaudeを例にすると、ウェブでチャットできても、開発者プロジェクトが利用可能とは限りません。ウェブは正常でAPIにエラーが出る場合は、開発者コンソールで認証情報、プロジェクト、モデルを確認してください。ウェブのセッションを先に削除する必要はありません。逆に、APIから結果が返っても、同じユーザーがウェブ上のチームワークスペースを使えるとは限りません。個人用スペースではチャットできるのにチーム用スペースではできない場合、現在選択中のワークスペースを記録し、管理者にメンバーの状態と対象機能を確認してもらいましょう。問題の証明に会話全文を提出する必要はありません。
Geminiのアプリ、開発者ツール、クラウド環境は、それぞれ別の入口として扱います。組織で管理されているアカウントは、ログイン後もアプリのライセンスやプロジェクトのポリシーによって利用が制限される場合があります。まずアカウントとプロジェクトを確認し、利用したい機能が有効かを調べてください。「権限がありません」と表示された場合は、アカウント、プロジェクト、リソースのどれに問題があるか、エラーの内容を確認します。個人向けアプリを使えても、会社のプロジェクトでAPIが許可されているとは限りません。会社の環境で個人アカウントを代わりに使うと、データの保存先や請求先が変わるため避けてください。
エディター、クラウドタスク、生成物をそれぞれ確認する
Copilotの問題を調べるときは、まず製品名を正確に確認してください。エディター向けのGitHub Copilotと、業務環境向けのMicrosoft 365 Copilotは別の製品です。一方のライセンスや拡張機能の状態から、もう一方が使えるとは判断できません。Cursorでは、エディターにログインできるか、選択中のモデルを呼び出せるか、実際のリクエストを送る機能が動作するかを分けて確認します。リモートワークスペースだけでエラーが出る場合は、リクエストがローカルの画面、リモートの拡張プロセス、サービスのどこから送られているかを調べてください。ローカルブラウザーの結果から分かるのは、ローカル画面の経路だけです。
Midjourneyのような非同期生成サービスでは、操作を送信、待機・実行、生成物の表示に分けて考えます。画面がすぐに更新されない場合は、まず元のタスクが受け付けられているか確認してください。タスクが存在し実行中なら、同じ内容をすぐに再送しないでください。タスクが完了しているのに画面に表示されない場合は、送信失敗ではなく生成物の読み込みを調べます。デスクトップアプリ、ウェブ、その他の公式入口で結果が異なる場合は、入口とアカウントの組み合わせを記録し、サービス状況やエラーの説明と照らし合わせてください。プラットフォームを比較するときは、トップページが開くかどうかではなく、同じ機能を実行した結果を比べます。
// ROUTE REVIEW
回線の確認:名前解決・ハンドシェイク・出口
まず実際に使われた接続経路を確認する
回線を選ぶ前に、サービスの利用条件とネットワーク経路を分けて確認してください。K3VPNは120+か国、170+回線をカバーしています。対応地域と回線の種類はサーバー一覧をご覧ください。このカバー範囲は、サードパーティーツールの利用可能地域を示すものではありません。サービスのポリシーに従ったうえで、タスクに適した接続経路を比較する目的で回線を選びます。回線の種類が分からない場合は、地域・種類・用途に応じた回線の選び方を確認し、下の表を参考に同じ操作を再現してください。
| 回線の種類 | 見方 | 確認方法 |
|---|---|---|
| IEPL専線 | 国際区間の通信経路に注目する | 同じ時間帯に同じ生成タスクを実行する |
| 中継 | リクエストが中継ノードを経由する | 接続確立と出力中断の有無をそれぞれ確認する |
| 直接接続 | クライアントから選択したノードに直接接続する | 利用中のネットワークから該当ノードへの接続を確認する |
OSのプロキシ設定、ブラウザー独自のネットワーク設定、クライアントのルール、ターミナルのプロセス設定は一致しないことがあります。分割トンネルを使っている場合、サービスのトップページに適用されたルールが、認証ページ、API、添付ファイル用のサービスにも適用されるとは限りません。クライアントの接続ログを確認できる場合は、リクエストの発生時刻をアプリと接続先ホストに照らし、想定したルールが適用されているか確認してください。組織の端末では管理者が承認した設定に従い、管理ポリシーによる制限がある場合は、システムの信頼設定や接続ルールを勝手に変更しないでください。
名前解決、接続、証明書を別々の段階として確認する
ドメイン名を解決できない場合、リクエストはまだアプリケーション層に到達していません。まず公式ドキュメントに記載されたホスト名を使っているか確認し、実際に失敗するプロセスや実行環境で名前解決を調べます。ブラウザーとコマンドラインでは名前解決の方法が異なることがあり、ローカル端末で取得したアドレスがコンテナ内でも使われるとは限りません。名前解決でアドレスが返っても接続できない場合は、プロキシへの接続、接続先、ハンドシェイクのどの段階でタイムアウトするか確認します。名前解決の結果は、名前に対する応答があったことを示すだけで、サービスが利用可能だという根拠にはなりません。
証明書エラーは別に対処します。端末の時刻、アクセス先のホスト名、アプリが使用する信頼ストアを確認してください。組織管理の端末が検査用ゲートウェイを経由する場合は、正式な信頼設定を管理者に確認します。証明書のホスト名が一致しない、発行者に異常があるといった場合は、そこで操作を止めてください。認証情報を入力したり、一度だけ応答を得るために証明書検証を無効にしたりしないでください。ブラウザーでは問題なく、コマンドラインで証明書エラーが出る場合は、クライアントを再インストールしたり回線を次々に変えたりするより、両者の信頼元を比較するほうが原因を絞り込めます。
日常利用を代表するタスクで比較する
通常のチャットは個人情報を含まない短い入力で試します。継続的な出力は、複数の文章を安定して生成できる同じリクエストで確認します。添付ファイルは機密情報を含まないサンプルを使ってください。モデル、入口、アカウントを変えず、同じ時間帯の経路を比較します。接続が確立したか、出力が始まったか、最後まで完了したかを記録してください。短いリクエストは成功し、長いリクエストだけ失敗する場合は、ゲートウェイやクライアントのタイムアウト処理を確認します。アップロードだけが失敗する場合は、添付の段階を個別に調べてください。ウェブページが開く速さからツール全体の使い心地を推測したり、サービスの待ち行列を回線切断として記録したりしないようにしましょう。
// IDENTITY FLOW
アカウントへのログイン:認証元とアカウントの所属
ログイン前に認証元とアカウントの所属を確認する
まずサービスの公式入口を開き、アカウントの種類、利用可能な地域、必要な認証情報を確認します。企業で利用する場合は、どの組織アカウントでログインするか、管理者から招待されているか、対象のワークスペースにアカウントが登録済みかも確認してください。組織のシングルサインオンを使っていた場合は、同じ方法でログインします。表示名が同じ、あるいはアカウント識別子が似ているだけでは、入口で同一の利用者として認識されるとは限りません。ログイン方法を変えた後に履歴が見つからない場合は、データが消えたと決めつける前に、別のアカウントやワークスペースに入っていないか確認してください。
K3VPNの利用登録にメールアドレスは不要で、ユーザー名とパスワードで登録できます。この条件はK3VPNに限られます。サードパーティーのAIプラットフォームでは、それぞれの利用条件に従ってください。サービスごとに異なる認証情報を使い、組織アカウントは社内の手順に沿って管理します。課金を有効にする場合や登録情報を修正する場合は、公式のアカウント設定で地域、請求先、支払い条件を確認してください。情報が一致しない場合は修正するかサポートに問い合わせ、審査を通過するために虚偽の情報を使わないでください。一時的な認証情報を含むリンクを、グループチャットや問い合わせチケットに転送することも避けてください。
認証前と認証後、どちらで失敗したかを見分ける
ブラウザーがサービス画面から認証プロバイダーに移動した後、認証に成功しても、サービス側でセッションが確立したとは限りません。認証サービスからブラウザーが所定のURLに戻り、サービスが同じ手続きで発行した状態情報を確認する必要があります。同じブラウザープロファイルと一連の手続きで最後まで進めてください。途中のURLを別のウィンドウや端末にコピーして続けないようにします。ブラウザーがページ間を行き来する場合は、エラーが表示されたページ名、ドメイン、機密情報を含まないエラー内容を記録し、サイトの保存データやリダイレクトが消去・ブロックされていないか確認してください。
ブラウザーの問題が確認できている場合は、すべてのサイトデータを消去せず、まず新しいプロファイルで検証できます。プライベートブラウズは拡張機能の影響を調べるのに使えますが、保存データやクロスサイト制限が通常のウィンドウと異なる場合があります。成功しても失敗しても、それだけで原因となる設定を特定することはできません。サービスから同じブラウザー内で認証するよう求められた場合は、元のサービス入口に戻り、手続きを最初からやり直してください。組織管理の端末では、拡張機能やブラウザーのポリシーは管理者が管理します。テストのためにセキュリティ制限をすべて無効にしないでください。
アカウント認証と組織の権限エラーを切り分ける
サービスから追加の本人確認を求められた場合は、既存の公式復旧手段を使って対応します。ログイン画面では認証済みと表示されるのにサービスに戻るとエラーになる場合は、招待を承認したか、メンバー資格が有効か、正しい組織に入っているかを管理者に確認してもらってください。チームの権限を変更した後は、公式の案内に従ってセッションを再確立し、プロフィール画像が表示されるかではなく、使えなかった機能を試して確認します。個人アカウントで同じページを開けても、別の権限が有効だと分かるだけで、チームアカウントやネットワーク経路に問題があるとは判断できません。
不審なログイン通知を受け取ったら、最近のアカウント利用状況と許可済みアプリを確認し、心当たりのないセッションを取り消して、公式の案内に従い該当する認証情報を変更します。利用停止や審査に関する通知が表示された場合は、ログインを繰り返したり、復旧の代わりに新しいアカウントを作ったりしないでください。サポートには、発生した時間帯、利用した入口、組織名、機密情報を除いたエラー内容を伝えます。追加資料が必要な場合は、プラットフォーム指定の窓口だけを利用してください。アカウント設定には入れるのに目的のタスクを実行できない場合は、同じアカウントで機能の利用許可と課金状況を確認します。複数のアカウントを行き来すると記録が混乱するため避けてください。
// STREAM LIFECYCLE
ストリーミング出力:最初の出力・間隔・完了
リクエストの成功は出力の完了を意味しない
ストリーミングでは、タスクが完了するまで出力が少しずつ届きます。リクエストが成功しても、その後にネットワーク切断、サービスエラー、クライアントによるキャンセルが起き、完了しないことがあります。リクエストを送ってから最初の出力が届くまでの時間、出力片の間の停止時間、タスクが正常に完了したかを分けて確認してください。最初の出力が遅い場合は、待ち行列、モデルの準備、経路上のバッファリングが考えられます。出力が届いた後に長時間止まる場合は、アイドルタイムアウトや途中切断を調べます。生成が終わっているのに画面が読み込み中のままなら、クライアントが完了イベントを認識しているか確認してください。
ウェブでは、開発者ツールのネットワークパネルに現在のセッション内のリクエスト一覧を残し、送信した時刻に対応するリクエストを確認できます。応答の有無、ブラウザーによるキャンセル表示、ページから代替リクエストが送信されたかを調べます。ツールでイベント全体を読み取れなくても、イベントが届いていないとは限りません。まずブラウザーがその通信方式をサポートしているか確認してください。ネットワーク記録を丸ごと他者に渡さず、失敗した段階、公開されているエラー情報、リクエスト識別子だけを抜き出します。サービスにタスク履歴がある場合は、元のタスクの最終状態も確認し、画面上の観察を補ってください。
タイムアウトとバッファリングを分けて検証する
接続タイムアウトは接続を確立できるかどうかに関するもので、最初の応答を待つ時間やリクエスト全体の制限時間とは異なります。読み取りタイムアウトは、一定時間内に新しいデータを受信できるかを扱う場合があります。具体的な意味は利用するクライアントのドキュメントを確認してください。リバースプロキシには、上流への接続に対する独自の制限が設けられていることもあります。出力がほぼ同じ無通信時間の後に止まる場合は、クライアント、アプリケーションサービス、ゲートウェイそれぞれの制限時間を照らし合わせます。リクエスト元のタイムアウトを延ばしても、ゲートウェイが先に接続を閉じる問題は解決しません。すべての制限時間を延ばすと、原因を見えにくくし、接続を長時間占有するおそれがあります。
バッファリングでは、データが途中の層に蓄積され、後からまとめて送信されます。待ち時間の後に内容が一度に届き、タスク自体は中断していない場合は、同じ公式サポート対象のストリーミングAPIを、許可された直接接続とアプリケーション経由の両方で比較できます。コマンドラインでストリームを受信する場合は、出力を確認しやすくするため、コマンドラインツール側のバッファリングを無効にできます。ただし、上流のゲートウェイにおけるバッファリングは変わりません。アプリケーションがイベント単位で画面を更新するのか、受信済みのデータをメモリに蓄積して最後に表示するのかも確認してください。
生成、アップロード、復旧はそれぞれ異なる操作
添付ファイルを含むタスクでは、まずアップロードが成功したことを確認してから、解析と生成を調べます。テキストだけならストリーミング出力できるのに、添付すると生成前に失敗する場合は、ファイル形式、サイズ制限、選択した機能を確認し、アップロードに対してアプリが受け付ける認証情報が返っているか調べてください。機密情報を除いたテストファイルを使い、実際のファイルを繰り返しアップロードして再現しないでください。動画や画像などの非同期タスクは、チャット出力の待ち方で成否を判断せず、元のタスクの状態を確認します。
ストリームが中断した場合は、受信済みの内容を保存し、未完了として扱います。クライアントが同じ生成リクエストを黙って再送してはいけません。上流ですでに一部または全部が実行されている可能性があり、再送すると結果が重複したり、追加料金が発生したりする場合があります。公式の照会・復旧機能があれば、まず元のタスクを確認してください。復旧機能がない場合は、再送するかどうかをユーザーまたは上位の業務処理に委ねます。調査後は同じ入力でもう一度検証し、出力が最後まで完了すること、画面の待機状態が解除されること、中断時に受信済みの内容と最終結果を区別できることを確認してください。
// API CONTRACT
APIの呼び出し:認証情報・プロジェクト・エラー
最小限のリクエストでAPI仕様を確認する
ウェブ版のセッションはAPIの認証情報ではありません。リクエストを送る前に、公式の開発者ドキュメントでAPIのURL、認証方式、モデルID、リクエスト形式、課金対象のプロジェクトを確認してください。クライアントが実際に使うサービス、モデル、プロジェクトが、コンソールで確認しているものと同じか確かめます。設定ファイル、環境変数、コマンドライン引数は互いの設定を上書きする場合があります。優先順位はツールのドキュメントを参照してください。有効なホスト名、モデル、プロジェクトの別名は記録し、秘密鍵の値は表示しないでください。ブラウザーのセッション情報を開発者向け認証情報の代わりに使うこともできません。
最初の検証ではストリーミング、添付ファイル、ツール呼び出し、長い会話履歴を外し、公式サンプルに必要な項目だけを残します。機密情報を含まない短い入力で認証、プロジェクト、モデルを確認してください。成功したら業務用のパラメーターを一つずつ戻し、どの機能や入力で違いが生じるか調べます。最小リクエストでも料金が発生する場合があります。頻繁に実行されるヘルスチェックにテストを組み込まないでください。HTTPS接続を確立できるかだけを先に確かめる場合は、次のコマンドを実行できます。これは公開サンプルサイト向けの例です。実際の調査では公式ドキュメントでホスト名を確認し、最初は認証情報を送信しないでください。
curl --silent --show-error --output /dev/null \
--write-out 'HTTP %{http_code}\n' \
https://example.com/
このコマンドは、Unix系のコマンドラインを使う環境向けです。レスポンス本文は表示せず、既定ではリダイレクトにも追従しません。HTTPステータスが返っても、応答があったことを示すだけで、プロジェクトの権限やストリーミングAPIの動作を証明するものではありません。後から認証付きリクエストを行う場合は、コマンドのトレース、詳細なネットワークログ、自動化ログに何が出力されるか特に注意してください。可能であればプラットフォームのSDKと実行環境のシークレット管理機能を使い、ログには機密情報を除いたエラーの種類、リクエスト識別子、呼び出し段階だけを残してください。
まずエラーの発生元と本文で分類する
| 確認する内容 | まず確認する項目 | 次の手順 |
|---|---|---|
| HTTP応答をまだ受け取っていない | 名前解決、ルーティング、証明書、タイムアウト | 実際にリクエストを送信した環境で再確認する |
| 認証または権限に関する通知 | 認証情報、プロジェクト、ロール、モデルの利用資格 | エラー本文に応じて該当するコンソールを確認する |
| 入力またはモデルのパラメーターエラー | 項目の形式、モデル名、機能の対応状況 | 公式の最小リクエストに戻し、項目を一つずつ追加する |
| レート制限または残高に関する通知 | 制限対象、使用量、プロジェクトの所属 | 一時的なレート制限と利用枠の超過を区別する |
| 応答成功後に接続が切れる | 完了イベント、アイドルタイムアウト、バッファリング | ストリーミング出力の段階ごとに記録を比較する |
同じHTTPステータスでも、組織のゲートウェイが返した場合とサービス自体が返した場合があります。まず応答元を判断し、エラーの種類について公式ドキュメントの説明を確認してください。本文が想定した形式ではなくプロキシのログインページなら、アプリケーション層で解析エラーとして表示されても不思議ではありません。エラーがプラットフォームから返され、プロジェクトに指定機能の利用資格がないと示されている場合は、接続元を次々に変えて試さないでください。コンソールでロール、モデルの提供範囲、請求状況を確認するか、プロジェクト管理者に機能を有効にすべきか確認してください。
ウェブ版と比較するときは同じ操作を比べる
ウェブ版では通常、アカウントセッション、ワークスペース、操作画面も関わります。一方、APIでは送信したリクエストのパラメーターを確認します。コマンドラインでは成功しウェブ版では失敗する場合は、認証後のリダイレクト、フロントエンドのリソース、サービスの利用許可を確認してください。ウェブ版は使えるのにAPIで失敗する場合は、認証情報とプロジェクトを調べます。両方で失敗する場合も、同じネットワーク、同じ時間帯にアクセスしているか、同じモデル機能を使っているかを確認してください。調査を終えるときは、変更したパラメーターと解消したエラーを記録し、検証用の最小リクエストと本番の業務リクエストをそれぞれ再利用できるテストとして保存します。
// RUN CONTEXT
開発環境:ターミナル・エディター・CI
ターミナル:現在のプロセスが引き継いだ設定を確認する
ターミナルでは、実際のリクエストは現在のツールとランタイムから送信されるため、デスクトップブラウザーのプロキシルールがそのまま使われるとは限りません。コマンドがホストOS、サブシステム、コンテナ、リモートホストのどこで実行されているかを確認し、ツールが環境のプロキシ設定を認識しているか調べます。環境変数の書き方、例外ルール、優先順位はツールによって異なります。あるランタイムの経験をすべてのコマンドに当てはめないでください。関係する設定が存在するか、承認された設定元から値を取得しているかだけを確認し、環境変数をすべてコンソールやログに出力しないようにします。
環境を調べるときは読み取り専用の接続テストを優先し、デバッグ用コマンドに秘密鍵を直接貼り付けないでください。コマンド履歴やプロセス引数に記録される可能性があります。コンテナ内では失敗し、ホストでは成功する場合は、コンテナ内の名前解決、証明書の信頼設定、実際に適用される設定を確認します。コンテナ内のループバックアドレスはコンテナ自身を指し、ホストで同じ表記をしたアドレスとは別の場所です。組織のプロキシを使う必要がある場合は、環境の提供元が定める接続方法を使います。ローカルの待ち受けポートを一時的に外部公開すると、局所的な調査が新たな接続リスクにつながるため避けてください。
エディター:画面と拡張機能のプロセスを分けて確認する
CursorやCopilot対応エディターは、起動時にデスクトップのセッションから環境を読み込む場合があります。一方、統合ターミナルは独自の起動スクリプトから設定を読み込みます。統合ターミナルからリクエストを送信できても、そのプロセスが使えることを示すだけで、拡張機能のホストが同じ設定を受け取ったとは限りません。まずエディターや拡張機能のログで、ログイン、リクエストの構築、通信のどの段階で失敗しているかを調べます。その後、拡張機能がローカルとリモートのどちらで動いているか確認してください。リモートワークスペースでは、証明書ストア、環境設定、アカウントの利用許可、接続元をそれぞれリモート環境で確認する必要があります。
承認された設定を変更した後は、エディターや拡張機能の説明に従って、影響を受けたプロセスを再読み込みします。機密情報を含まない同じ最小操作で再確認してください。コード補完は動くのにチャットが失敗する場合、プラグイン全体の接続に問題があると決めつけないでください。機能の入口、モデル、ワークスペースを個別に記録します。企業ではファイルのコンテキスト、コード片、添付ファイルが組織のデータポリシーの対象となる場合があります。診断には専用のサンプルプロジェクトを使い、承認されていないサービスに本番リポジトリの内容を送信しないでください。プロンプトを含む拡張機能のログを公開の問い合わせに添付することも避けます。
継続的インテグレーション:ジョブの実行環境から調べる
CIの接続元は、コードをコミットした端末ではなく、ジョブを実行する環境です。ホスト型とセルフホスト型の実行環境では、外向き通信のルール、信頼ストア、認証情報の注入方法が異なる場合があります。まず承認されたテストジョブで公開対象への接続を確認し、専用のテストプロジェクトで最小限の権限を使った呼び出しを行います。保護された環境変数が対象のブランチとジョブから参照できるかも確認してください。外部のコントリビューターによるビルドは、プラットフォームの隔離ルールに従って実行します。APIの診断を理由に、信頼できないビルド環境へ本番用の認証情報を公開しないでください。
ジョブの記録には、プロジェクトの別名、リクエストの種類、ステータス、終了理由だけを残し、認証情報を含むコマンド全体、リクエストヘッダー、未加工の成果物は保存しないでください。一つのワークフローから複数のタスクを並行実行できる場合は、設定に並列数と予算を記録し、呼び出し総数を管理できるようにします。まず単発の呼び出しと予定している並列実行を別々に確認してください。単発では成功し、並列実行で失敗する場合は、ワークフロー全体を繰り返し実行するのではなく、レート制限やキューを調べます。権限エラーはプロジェクト管理者へ、接続エラーは実行環境の管理者へ共有するほうが、各自の端末から個別に検証するより早く解決できます。
// LIMITS AND RECOVERY
レート制限と復旧:待機・利用量・申し立て
まずレート制限、利用枠、アカウント審査のどれかを確認する
制限には複数の種類があります。レート制限は一定時間内のリクエスト数やモデルの使用量に関するもの、プロジェクトの利用枠は課金状況に関するもの、アカウント審査は本人確認やコンプライアンスに関する別の手続きです。失敗した機能、プロジェクト、エラー本文を記録し、該当する公式コンソールで利用量と状態を確認してください。ウェブに「時間をおいて再試行」と表示されても、組織が利用停止になったとは限りません。APIの呼び出しが拒否されても、ウェブ版に問題があるとは限りません。アカウント停止や利用地域に関する通知が明示されている場合は、自動的な再試行を止め、短時間のレート制限と考えて待つのではなく、公式の復旧手続きを進めてください。
見落としやすい要因が同時実行数です。利用者が一人だけに見えるサービスでも、ウェブ操作、バックグラウンドタスク、CIジョブ、クライアントの複数段階の再試行が同時に走る場合があります。まずアプリ側で成功、失敗、キャンセル、再試行を集計し、プロジェクトコンソールの計測方法と照らし合わせてください。ユーザーの一回の操作が一回のリクエストだと決めつけたり、ウェブのサブスクリプション状況からAPIの残高を推測したりしないでください。プロジェクトの利用量が想定より多い場合は、重複実行、リクエストコンテキストの増加、一つのタスクが複数回の呼び出しに分かれていないか調べてから、並列数を減らすか入力を短くするか判断します。
再試行する場合も回数や条件を決める
サービスが再試行を許可している場合は、Retry-Afterなど、ドキュメントに記載された待機時間の指示に従います。待機方法が示されていない場合は、上限付きの指数バックオフに少しランダムな待機時間を加え、並列タスクが同時に再送されるのを防ぎます。再試行を担当する層を一つに決めてください。SDK、業務サービス、ジョブスケジューラーがそれぞれ再試行すると、予想外に呼び出し数が増える可能性があります。クライアントから待機をキャンセルできるようにし、タスク全体にも制限時間を設けます。残高不足、認証エラー、モデルの利用不可、パラメーターの誤りは、通常、条件を先に修正する必要があります。同じリクエストを再送しても解決しません。
料金が発生する操作、記録を変更する操作、タスクを作成する操作では、切断後に前回の操作が実行されなかったと決めつけないでください。まず元のリクエスト識別子を使い、プラットフォームが照会を認めている状態を確認します。APIが冪等キーに対応している場合は、公式ルールに従い、同じ業務操作には同じキーを再利用してください。すべてのAPIが対応していると独自に判断してはいけません。状態を照会できる場合は、実際の結果に基づいてキュー側で補完処理を判断します。照会できない場合は、不確定な状態をタスク記録に残し、必要に応じて人が確認してください。ストリーミング内容が一部表示された場合は、それが中断した試行から届いた内容だとユーザーに分かるようにします。
審査に関する通知は公式窓口で対応する
制限の通知を受け取ったら、まず発生時刻と公式の案内を保存し、製品の利用条件を超える使い方、組織ポリシーとの不一致、不審な認証情報の利用、未処理の請求がないか確認してください。情報漏えいの疑いがある場合は、影響を受けた認証情報を取り消し、呼び出し履歴を確認し、正当な利用者の設定を更新します。管理対象のアカウントであれば、速やかに管理者へ連絡してください。申し立てでは実際に行った操作のみを説明し、プラットフォームが求める最小限の情報を提出します。秘密鍵、セッション情報、ログイン後のリダイレクトURL、業務データが写った画面は送らないでください。審査や復旧の代わりに、アカウントや接続元を切り替えて回避しようとしないでください。
復旧後は負荷の低い最小限のタスクから始め、対象機能が再び利用できることと利用枠を確認してから、通常の並列数に段階的に戻します。同じ問題が繰り返し起きる場合は、原因の分類、発生条件、担当者を運用手順書に記録し、アプリ内で待機や停止の案内を分かりやすく表示してください。K3VPNの接続に関する問題はヘルプセンターで確認できます。初期設定は初回利用ガイドをご覧ください。サードパーティープラットフォームのアカウント、モデル、利用枠の問題は、該当するプラットフォームまたは組織の管理者に問い合わせてください。