Headless APIのトラブルシューティング ​

このページを使用して、一般的なHeadless APIの失敗を解決します。

Headless APIが有効になっていることを確認する ​

Headless APIはプライベートベータ版です。 次の場合、ワークスペースで有効になっていない可能性があります。

• Genieチャットインターフェースにcustom chat interfaceオプションが表示されない
• 以下のケースに到達する前に、ランタイム呼び出しが拒否される

アクセスをリクエストするには、Customer Success Managerにお問い合わせください。

401 auth_failed ​

エラー: ランタイム呼び出しで401が次の内容とともに返されます。

{ "error_code": "auth_failed", "error_message": "Authentication failed.", "request_id": "<uuid>" }

原因と解決策: ゲートウェイがGenieに到達する前に認証情報を拒否しました。 次の項目を順番に確認します。

• トークンのタイプが間違っている: ランタイム呼び出しでは、プロビジョニング専用のwrkaus-… Developer APIトークンではなく、GenieクライアントAPIキーまたはOAuthアクセストークンを使用します。
• データセンターが間違っている: 認証情報はデータセンターごとにスコープ設定されます。 ワークスペースが実行されているデータセンターと同じデータセンターのgenie-apiホストを呼び出します。
• 期限切れまたはローテーション済みのキー: APIキーを再生成すると、以前のAPIキーは無効になります。 再生成し、更新されたAPIキーを使用するようにバックエンドを更新します。
• 形式が正しくないヘッダー: Authorization: Bearer <token>を正確に送信します。

401 user_nonactive_or_missing ​

エラー: APIキー呼び出しでerror_code: "user_nonactive_or_missing"とともに401が返されます。

原因: X-IDP-User-Idがアクティブで許可リストに登録されたユーザーに解決されません。 ユーザーが存在しない場合、Genieで許可リストに登録されたユーザーグループに属していない場合、またはまだアクティブでない場合のいずれでも、ランタイムは同じコードを返します。 ユーザーは招待済みであっても、招待を承諾してWorkato Identityの設定を完了していない場合は非アクティブです。

解決策: ユーザーがアクティブであることを確認します。 招待されたユーザーは、アサートできるようになる前にメール招待を承諾し、Workato Identityの設定を完了する必要があります。そのため、設定が完了していない場合は、ユーザーにメールを確認するよう依頼してください。 次に、ユーザーがGenieで許可リストに登録されたユーザーグループに属していることを確認し、必要に応じて先にユーザーを作成します。 ランタイム呼び出しの前に、サーバー側でGET /api/iam/users?query=<email>を使用してユーザーを検索します。 レスポンスにはstatusフィールド（activeまたはinvited）が含まれます。これにより、不明なユーザーと許可リスト未登録のユーザーに対して異なるメッセージを表示することもできます。

クライアントの作成またはアタッチに失敗する ​

エラー: ほとんどのDeveloper API呼び出しは成功しますが、Genieクライアントの作成、再生成、またはアタッチが権限エラーで失敗します。

原因: Developer APIクライアントのロールに、クライアント管理を制御するGenie building配下のCustom chat interface権限がありません。 これはHeadlessの設定で最も見落とされやすい権限です。

解決策: 少なくともCreateの権限を持つCustom chat interfaceアクセスをロールに付与します。 権限を追加した後にトークンをローテーションする必要はありません。

関連: Genieにすでにクライアントがある場合、クライアントのアタッチで409が返されます。 関係は1:1です。 まず既存のクライアントをデタッチします。

空のストリームまたは空白イベントの繰り返し ​

エラー: SSEストリームは開いたままですがアイドル状態に見える、またはGenieがまったく応答しません。

原因と解決策:

• キープアライブイベント: 長時間実行中または一時停止中のターンでは、ランタイムが定期的なキープアライブイベントを出力します。 例: 約30秒ごとのsystem.ping。 ハンドラーが認識しないイベントタイプは無視します。
• Genieが開始されていない: Genieはアクティブである必要があります。 POST /api/agentic/genies/:id/startで開始します。
• ユーザーの操作待ち（スキル確認）: skill.confirmation_requiredイベントにより、スキルを承認または拒否で判断を投稿するまでターンが一時停止します。 解決内容を投稿すると同じストリームが再開されます。再接続する必要はありません。
• ユーザーの操作待ち（ランタイムコネクション）: runtime_connection.auth_requiredイベントにより、ユーザーがアウトオブバンドでアップストリームコネクションを認証している間、ターンが一時停止します。 クライアントが投稿する内容はなく、元のストリームは再開されません。 キープアライブを出力し、その後system.stream_interruptedを出力します。 statusがauthorizedになるまでランタイムコネクションリンクを取得をポーリングして完了を検出し、その後メッセージ履歴から再開された応答を読み取ります。

イベントリカバリで何も返されない ​

エラー: 切断後にイベントを取得でイベントが返されません。

原因: このエラーは、誤ったパラメータまたはウィンドウを使用した場合に発生します。 パラメータはsince_created_at（RFC3339タイムスタンプ）です。ページングするには、前回のレスポンスのnext_since_created_atを渡します。 イベントは24時間保持されます。

ファイルアップロードが拒否される ​

エラー: アップロードエンドポイントへの呼び出しが失敗する、またはGenieが添付ファイルを受信しません。

原因と解決策:

• ファイルが大きすぎる: 最大ファイルサイズは20 MBです。 ファイルを縮小するか分割します。
• リクエスト形式が間違っている: 単一のfileフィールドを使用して、ファイルをmultipart/form-dataとして送信します。 Content-Typeを手動で設定しないでください。 HTTPクライアントがmultipart境界を設定します。
• 添付ファイルが参照されていない: ファイルをアップロードしても、それだけでは添付されません。 返されたfile_idを、メッセージを送信のfile_idパラメータで渡します。

会話トピックでテキストではなく数値が返される ​

問題: GET /conversations/:conversation_idで、読み取り可能なタイトルではなく5951のような数値のtopicが返されます。

原因: Genieは、ユーザーの最初のメッセージから会話のtopicを自動生成しますが、これには少し時間がかかります。 生成が完了する前にGET /conversations/:conversation_idを呼び出すと、topicはまだ数値のプレースホルダーです。 会話を一覧表示エンドポイントは、準備が完了すると生成されたtopicを返します。

解決策: 表示には会話を一覧表示エンドポイントを使用するか、topicが数値の場合は会話の最初のユーザーメッセージにフォールバックします。

リロード後またはストリーム切断後に会話タイムラインを再構築する ​

問題: ページのリロード後またはSSEストリームの切断後に、skill.*イベントやprocessing.*イベントを含む完全なターンが必要ですが、ライブストリームで到着したものしかありません。

原因: ライブストリームだけでなく、すべての会話イベントが永続化されます。 skill.*やprocessing.*を含むすべてのイベントタイプは、発生後24時間、イベントを取得から取得できます。

解決策: GET /conversations/events?conversation_id=<conversation_id>&since_created_at=<RFC3339>で永続化されたイベントを取得し、順番に再生して完全なタイムラインを再構築します。 skill.*イベントとprocessing.*イベントをライブストリーム中にのみ利用可能なものとして扱わないでください。

例外が1つあります: runtime_connection.auth_requiredによる一時停止後に再開されたターンは、イベントを取得ではキャプチャされません。永続化されたイベントは一時停止時点で停止します。 その応答をメッセージ履歴からリカバリしてマージし、message_idで重複排除します。

ヘルプを利用する ​

すべてのランタイムレスポンスには、request_idとx-request-idヘッダーが含まれます。 Workatoサポートに問い合わせる際は、ゲートウェイでリクエストを追跡できるように、これらの値を含めてください。