Fouten afhandelen in een NextPDF Connect-workflow

In één oogopslag

Bouw veerkrachtige Connect-workflows. Valideer elk toolresultaat, sluit een mislukte sessie af en probeer het opnieuw vanuit een schone staat. Een mislukte tool retourneert een gestructureerd foutresultaat. Behandel dat resultaat als een normaal antwoord, niet als een transportstoring. PHP Standards Recommendation (PSR)-18 maakt hetzelfde onderscheid: er wordt een antwoord geretourneerd, ook wanneer de status een fout aangeeft (PSR-18 §3).

Installeren

composer require nextpdf/server

Bind een transport. Dit recept gebruikt create_pdf, add_text en output_pdf. Alle drie de tools zijn Core.

Conceptueel overzicht

Een mislukte toolaanroep retourneert een foutresultaat. Het resultaat bevat een foutvlag, een leesbaar bericht en, waar van toepassing, een code. Een geslaagd resultaat heeft geen foutvlag en bevat de normale uitvoer van de tool. In beide gevallen heeft het transport het verzoek verzonden en het antwoord ontvangen (PSR-18 §p2).

Houd de defensieve lus kort. Verstuur de aanroep en lees daarna het resultaat. Als het resultaat een fout is, log je de fout, classificeer je die, pas je de herstelstrategie toe en gebruik je geen verouderde staat meer. Anders haal je de velden eruit die je nodig hebt en ga je verder.

API-oppervlak

Tool	Rol	Risiconiveau
`create_pdf`	De sessie openen	Safe
`add_text`	Tekst schrijven	Caution
`output_pdf`	De PDF renderen en retourneren	Approval Required / Review (base64)

De tool-catalogus is de bron van waarheid. Welke tools beschikbaar zijn, hangt af van het geïnstalleerde niveau.

Codevoorbeeld — Snelstart

Voer het happy path uit (create_pdf → add_text → output_pdf) en controleer elk resultaat. Hergebruik vervolgens opzettelijk een vernietigde document_id bij add_text om een sessiefout te veroorzaken. Herstel door een nieuwe sessie aan te maken en de inhoud opnieuw af te spelen.

Codevoorbeeld — Productie

Classificeer fouten per categorie en reageer daar vervolgens op:

Invoervalidatie — deterministisch. Corrigeer de argumenten en probeer daarna dezelfde aanroep opnieuw. Voorbeelden: lege tekst, ongeldige uitlijning, niet-positieve grootte, onbekend paginaformaat, onbekende lettertypefamilie.
Sessie — de document_id bestaat niet meer. Maak een nieuwe sessie aan en speel daarna alle inhoud opnieuw af.
Systeem — een beperking van serverresources, zoals de sessielimiet. Wacht even en probeer het daarna opnieuw.
Goedkeuring — output_pdf naar een bestand kan pauzeren voor menselijke goedkeuring. Dit is een workflowpauze, geen storing. Geef de challenge door, wacht en roep de tool daarna opnieuw aan met het bevestigingstoken.

Ga er nooit van uit dat het is gelukt. Hergebruik nooit een document_id na een sessiefout. Verstuur output_pdf nooit voordat elke inhoudsstap is geslaagd.

Randgevallen en valkuilen

Goedkeuring is geen fout. De human-in-the-loop-challenge (HITL) is een pauze. Probeer niet in een strakke lus opnieuw. Geef de challenge door aan de mens.
Serverherstart. Alle sessies in het geheugen worden gewist en elke eerdere document_id wordt ongeldig.
Gedeeltelijke workflow. Als add_text halverwege het document mislukt, kan de sessie inconsistent zijn. Veilig herstel betekent een verse sessie, geen gedeeltelijke reparatie.

Prestaties

Verwaarloosbaar. Dit recept behandelt de besturingsstroom, niet de rendering. Het profiel is structural voor elke geproduceerde uitvoer.

Beveiligingsnotities

Foutmeldingen zijn bedoeld voor de aanroepende agent en operator. Geef ruwe serverfouttekst niet woordelijk door aan niet-vertrouwde eindgebruikers. Toon in plaats daarvan een geclassificeerd, opgeschoond bericht.

Conformiteit

Bewering	Spec	Clausule	reference_id
Het transport retourneert een antwoord, ongeacht het resultaat.	PSR-18	§p2
Zelfs bij een foutstatus wordt een antwoord geretourneerd.	PSR-18	§3

Commerciële context

Niet van toepassing — alle tools zijn Core.

Transportbeschikbaarheid

Transport	Beschikbaar	Notities
MCP (stdio)	Ja	Fouten arriveren als een toolresultaat met een foutvlag.
REST	Ja	Een status buiten het 2xx-bereik bevat dezelfde geclassificeerde foutinhoud.
gRPC	Ja	Een statuscode plus een bericht met het foutresultaat.

Inspecteer bij elk transport een fout op toolniveau als een normaal antwoord, niet als een verloren aanroep (PSR-18 §3).

HITL-risiconiveau

create_pdf is Safe, add_text is Caution en output_pdf is Approval Required, in base64-modus verlaagd tot Review. Een nog uit te voeren bestandsschrijfactie verschijnt als de goedkeuringschallenge. De foutlus moet die behandelen als een pauze, niet als een storing (HITL-risiconiveaus).

JSON-envelop van de bevestigingsgate

Een nog uit te voeren goedkeuring retourneert:

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

Roep dezelfde tool opnieuw aan met _confirmation_token ingesteld op dat token. Die retourneert { "allowed": true }. Zie output-approval voor de volledige flow.