NextPDF Connect ワークフローのエラーを処理する

概要

回復力のある Connect ワークフローを構築します。すべてのツール結果を検証し、失敗したセッションは破棄して、新しい状態で再試行します。失敗したツールは構造化されたエラー結果を返します。これは正常な応答であり、トランスポートの障害ではありません。PSR-18 も同じ区別をしています。ステータスがエラーを示していても、応答は返されます（PSR-18 §3）。

インストール

composer require nextpdf/server

トランスポートをバインドします。このレシピでは create_pdf、add_text、output_pdf を使用します。これらはいずれも Core です。

概念の概要

失敗したツール呼び出しはエラー結果を返します。エラー結果にはエラーフラグと人間が読めるメッセージがあり、該当する場合はコードも含まれます。成功した結果にはエラーフラグがなく、ツールの通常出力が含まれます。いずれの場合も、トランスポートはリクエストを送信し、応答を受信しています（PSR-18 §p2）。

防御的なループは短く保ちます。呼び出しを送信し、結果を読み取ります。エラーであれば、ログに記録して分類し、回復戦略を適用します。古い状態のまま処理を続行しないでください。そうでなければ、必要なフィールドを抽出して続行します。

API サーフェス

ツール	ロール	リスク階層
`create_pdf`	セッションを開く	Safe
`add_text`	テキストを書き込む	Caution
`output_pdf`	PDF をレンダリングして返す	承認が必要 / レビュー（base64）

ツールカタログが正式なカタログです。利用可能なツールは、インストール済みのティアによって異なります。

コードサンプル — クイックスタート

正常系（create_pdf → add_text → output_pdf）を実行し、各結果を確認します。次に、破棄済みの document_id を add_text で意図的に再利用して、セッションエラーを発生させます。新しいセッションを作成し、コンテンツを再適用して回復します。

コードサンプル — 本番

エラーをカテゴリー別に分類し、それに応じて対応します。

入力検証 — 決定論的です。引数を修正し、同じ呼び出しを再試行します。例：空のテキスト、不正な配置、非正のサイズ、不明なページサイズ、不明なフォントファミリー。
セッション — document_id はすでに存在しません。新しいセッションを作成し、すべてのコンテンツを再適用します。
システム — セッション上限など、サーバー側のリソース制約です。バックオフして再試行します。
承認 — ファイルへの output_pdf は、人間による承認のために一時停止することがあります。これはワークフローの一時停止であり、障害ではありません。チャレンジを中継して待機し、その後、確認トークンを付けて再呼び出しします。

成功を決して前提にしないでください。セッションエラーの後は document_id を決して再利用しないでください。すべてのコンテンツ手順が成功するまでは、output_pdf を決して送信しないでください。

エッジケースと注意点

承認はエラーではありません。 HITL チャレンジは一時停止です。タイトなループで再試行しないでください。人間に中継してください。
サーバーの再起動。 すべてのインメモリセッションがクリアされ、以前の document_id はすべて無効になります。
部分的なワークフロー。 add_text がドキュメントの途中で失敗すると、セッションに不整合が生じる可能性があります。安全な回復方法は、部分的な修復ではなく、新しいセッションを作成することです。

パフォーマンス

影響は無視できる程度です。このレシピは制御フローに関するものであり、レンダリングに関するものではありません。生成されるあらゆる出力について、プロファイルは structural です。

セキュリティに関する注意

エラーメッセージは、呼び出し側のエージェントとオペレーターに向けたものです。信頼できないエンドユーザーに、生のサーバーエラーテキストをそのまま表示しないでください。代わりに、分類しサニタイズしたメッセージを表示してください。

準拠

記述	仕様	条項	reference_id
トランスポートでは結果にかかわらず応答が返ること	PSR-18	§p2
エラーステータスでも応答が返ること	PSR-18	§3

商業的なコンテキスト

該当なし — すべてのツールは Core です。

トランスポートの可用性

トランスポート	利用可否	備考
MCP（stdio）	はい	エラーフラグ付きツール結果としてのエラー
REST	はい	2xx 以外のステータスでも同じ分類済みのエラーボディを伝達
gRPC	はい	ステータスコードとエラー結果メッセージ

すべてのトランスポートにおいて、ツールレベルのエラーは検査すべき正常な応答であり、呼び出しのドロップではありません（PSR-18 §3）。

HITL リスク階層

create_pdf は Safe、add_text は Caution、output_pdf は承認が必要で、base64 モードでは Review に格下げされます。保留中のファイル書き込みは承認チャレンジとして現れますが、エラーループではこれを障害ではなく一時停止として扱う必要があります（HITL リスク階層）。

確認ゲートの JSON エンベロープ

保留中の承認は次を返します。

{ "allowed": false, "challenge": "<human-readable challenge text>", "token": "confirm_<single-use-hex>" }

同じツールを、そのトークンを _confirmation_token に設定して再呼び出しすると、{ "allowed": true } を返します。完全なフローについては、output-approval を参照してください。