Fehler in einem NextPDF Connect-Workflow behandeln

Auf einen Blick

Erstellen Sie robuste Connect-Workflows. Validieren Sie jedes Tool-Ergebnis, verwerfen Sie eine fehlgeschlagene Sitzung und versuchen Sie es mit frischem Zustand erneut. Ein fehlgeschlagenes Tool gibt ein strukturiertes Fehlerergebnis zurück; das ist eine normale Antwort, kein Transportfehler. PSR-18 trifft dieselbe Unterscheidung: Eine Antwort wird auch dann zurückgegeben, wenn der Status einen Fehler anzeigt (PSR-18 §3).

Installation

composer require nextpdf/server

Binden Sie einen Transport ein. Dieses Rezept verwendet create_pdf, add_text und output_pdf, die alle zu Core gehören.

Konzeptioneller Überblick

Ein fehlgeschlagener Tool-Aufruf gibt ein Fehlerergebnis zurück. Es enthält ein Fehler-Flag und eine menschenlesbare Meldung, gegebenenfalls mit einem Code. Ein erfolgreiches Ergebnis hat kein Fehler-Flag und enthält die normale Ausgabe des Tools. In beiden Fällen hat der Transport die Anfrage gesendet und die Antwort empfangen (PSR-18 §p2).

Die defensive Schleife ist kurz. Senden Sie den Aufruf und lesen Sie das Ergebnis. Wenn es einen Fehler signalisiert, protokollieren Sie ihn, klassifizieren Sie ihn, wenden Sie die Wiederherstellungsstrategie an und fahren Sie nicht mit veraltetem Zustand fort. Andernfalls extrahieren Sie die benötigten Felder und fahren fort.

API-Oberfläche

Tool	Rolle	Risikostufe
`create_pdf`	Sitzung öffnen	Sicher
`add_text`	Text schreiben	Vorsicht
`output_pdf`	PDF rendern und zurückgeben	Genehmigung erforderlich / Review (base64)

Der Tool-Katalog ist maßgeblich. Die verfügbaren Tools hängen von der installierten Stufe ab.

Codebeispiel — Schnellstart

Durchlaufen Sie den Erfolgspfad (create_pdf → add_text → output_pdf) und prüfen Sie jedes Ergebnis. Verwenden Sie anschließend bei add_text absichtlich erneut eine ungültige document_id, um einen Sitzungsfehler auszulösen. Stellen Sie den Workflow wieder her, indem Sie eine neue Sitzung erstellen und den Inhalt erneut abspielen.

Codebeispiel — Produktion

Klassifizieren Sie Fehler nach Kategorie und reagieren Sie entsprechend:

Eingabevalidierung — deterministisch. Korrigieren Sie die Argumente und wiederholen Sie denselben Aufruf. Beispiele: leerer Text, ungültige Ausrichtung, nicht positive Größe, unbekannte Seitengröße, unbekannte Schriftfamilie.
Sitzung — die document_id existiert nicht mehr. Erstellen Sie eine neue Sitzung und spielen Sie den gesamten Inhalt erneut ab.
System — eine serverseitige Ressourcenbeschränkung, etwa das Sitzungslimit. Warten Sie mit Backoff und versuchen Sie es erneut.
Genehmigung — output_pdf in eine Datei kann pausieren, bis eine menschliche Genehmigung vorliegt. Das ist eine Workflow-Pause, kein Fehlschlag. Geben Sie die Challenge weiter, warten Sie und rufen Sie dann erneut mit dem Bestätigungstoken auf.

Gehen Sie niemals von Erfolg aus; verwenden Sie niemals eine document_id nach einem Sitzungsfehler erneut; senden Sie niemals output_pdf, bevor jeder Inhaltsschritt erfolgreich war.

Grenzfälle & Fallstricke

Eine Genehmigung ist kein Fehler. Die HITL-Challenge ist eine Pause. Wiederholen Sie den Aufruf nicht in einer engen Schleife. Geben Sie sie an die zuständige Person weiter.
Server-Neustart. Alle In-Memory-Sitzungen werden gelöscht; jede frühere document_id wird ungültig.
Teilweise abgeschlossener Workflow. Wenn add_text mitten im Dokument fehlschlägt, kann die Sitzung inkonsistent sein. Die sichere Wiederherstellung ist eine frische Sitzung, keine Teilreparatur.

Performance

Vernachlässigbar. In diesem Rezept geht es um Kontrollfluss, nicht um Rendering. Das Profil lautet structural für jede erzeugte Ausgabe.

Sicherheitshinweise

Fehlermeldungen sind für den aufrufenden Agenten und den Betreiber bestimmt. Geben Sie rohen Server-Fehlertext nicht wortwörtlich an nicht vertrauenswürdige Endnutzer aus. Zeigen Sie stattdessen eine klassifizierte, bereinigte Meldung an.

Konformität

Aussage	Spezifikation	Klausel	reference_id
Der Transport gibt unabhängig vom Ergebnis eine Antwort zurück.	PSR-18	§p2
Eine Antwort wird auch bei einem Fehlerstatus zurückgegeben.	PSR-18	§3

Kommerzieller Kontext

Nicht anwendbar — alle Tools gehören zu Core.

Transport-Verfügbarkeit

Transport	Verfügbar	Hinweise
MCP (stdio)	Ja	Fehler werden als Tool-Ergebnis mit einem Fehler-Flag zugestellt.
REST	Ja	Ein Status außerhalb von 2xx enthält denselben klassifizierten Fehler-Body.
gRPC	Ja	Ein Statuscode plus eine Fehlerergebnis-Meldung.

Bei jedem Transport ist ein Fehler auf Tool-Ebene eine normale Antwort, die geprüft werden muss, und kein verworfener Aufruf (PSR-18 §3).

HITL-Risikostufe

create_pdf hat die Stufe Sicher, add_text die Stufe Vorsicht, und output_pdf die Stufe Genehmigung erforderlich; im base64-Modus wird es auf Review herabgestuft. Ein ausstehender Dateischreibvorgang erscheint als Genehmigungs-Challenge, die die Fehlerschleife als Pause behandeln muss, nicht als Fehlschlag (HITL-Risikostufen).

JSON-Envelope des Bestätigungs-Gates

Eine ausstehende Genehmigung gibt Folgendes zurück:

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

Rufen Sie dasselbe Tool erneut auf, wobei _confirmation_token auf dieses Token gesetzt ist; es gibt dann { "allowed": true } zurück. Den vollständigen Ablauf finden Sie unter output-approval.