Gestire gli errori in un flusso di lavoro NextPDF Connect

In sintesi

Costruire flussi di lavoro Connect resilienti. Convalidare ogni risultato di uno strumento, scartare una sessione fallita e riprovare con uno stato pulito. Quando uno strumento fallisce, restituisce un risultato di errore strutturato: è una risposta normale, non un guasto del trasporto. PSR-18 mantiene la stessa distinzione: una risposta viene restituita anche quando lo stato indica un errore (PSR-18 §3).

Installazione

composer require nextpdf/server

Associare un trasporto. Questa ricetta usa create_pdf, add_text e output_pdf, che sono tutti Core.

Panoramica concettuale

Una chiamata fallita a uno strumento restituisce un risultato di errore. Include un flag di errore e un messaggio leggibile da una persona, con un codice ove applicabile. Un risultato andato a buon fine non contiene alcun flag di errore e include l’output normale dello strumento. In entrambi i casi, il trasporto ha inviato la richiesta e ricevuto la risposta (PSR-18 §p2).

Il ciclo difensivo è breve: inviare la chiamata e leggere il risultato. Se il risultato segnala un errore, registrarlo, classificarlo, applicare la strategia di recupero e non procedere con uno stato obsoleto. Altrimenti, estrarre i campi necessari e continuare.

Superficie API

Strumento	Ruolo	Livello di rischio
`create_pdf`	Aprire una sessione	Sicuro
`add_text`	Scrivere testo	Attenzione
`output_pdf`	Eseguire il rendering e restituire il PDF	Approvazione richiesta / Revisione (base64)

Il catalogo degli strumenti è il riferimento per il catalogo. Gli strumenti disponibili dipendono dal livello installato.

Esempio di codice — Avvio rapido

Eseguire il percorso ideale (create_pdf → add_text → output_pdf) e controllare ogni risultato. Quindi riutilizzare intenzionalmente con add_text un document_id distrutto per innescare un errore di sessione. Recuperare creando una nuova sessione e riproducendo il contenuto.

Esempio di codice — Produzione

Classificare gli errori per categoria e rispondere di conseguenza:

Convalida dell’input — deterministica. Correggere gli argomenti e riprovare la stessa chiamata. Esempi: testo vuoto, allineamento non valido, dimensione non positiva, dimensione di pagina sconosciuta, famiglia di caratteri sconosciuta.
Sessione — il document_id non esiste più. Creare una nuova sessione e riprodurre tutto il contenuto.
Sistema — un vincolo di risorse del server, come il limite di sessioni. Attendere prima di riprovare.
Approvazione — output_pdf su file può fermarsi in attesa di approvazione umana. Questa è una pausa del flusso di lavoro, non un guasto. Inoltrare la sfida e attendere, quindi richiamare con il token di conferma.

Non presupporre mai il successo; non riutilizzare mai un document_id dopo un errore di sessione; non inviare mai output_pdf finché ogni passaggio di contenuto non è riuscito.

Casi limite e insidie

L’approvazione non è un errore. La sfida HITL è una pausa. Non riprovare in un ciclo serrato. Inoltrarla all’utente umano.
Riavvio del server. Tutte le sessioni in memoria vengono cancellate e ogni document_id precedente diventa non valido.
Flusso di lavoro parziale. Se add_text fallisce a metà del documento, la sessione può risultare incoerente. Il recupero sicuro è una nuova sessione, non una riparazione parziale.

Prestazioni

L’impatto sulle prestazioni è trascurabile. Questa ricetta riguarda il flusso di controllo, non il rendering. Il profilo è structural per qualsiasi output prodotto.

Note di sicurezza

I messaggi di errore sono destinati all’agente chiamante e all’operatore. Non riprodurre alla lettera il testo grezzo degli errori del server per utenti finali non attendibili. Esporre invece un messaggio classificato e sanificato.

Conformità

Affermazione	Specifica	Clausola	reference_id
Il trasporto restituisce una risposta indipendentemente dal risultato.	PSR-18	§p2
Una risposta viene restituita anche in caso di stato di errore.	PSR-18	§3

Contesto commerciale

Non applicabile — tutti gli strumenti sono Core.

Disponibilità del trasporto

Trasporto	Disponibile	Note
MCP (stdio)	Sì	Gli errori arrivano come risultato di uno strumento con un flag di errore.
REST	Sì	Uno stato diverso da 2xx include lo stesso corpo di errore classificato.
gRPC	Sì	Un codice di stato e un messaggio di risultato di errore.

In ogni trasporto, un errore a livello di strumento è una risposta normale da esaminare, non una chiamata persa (PSR-18 §3).

Livello di rischio HITL

create_pdf è Sicuro, add_text è Attenzione e output_pdf è Approvazione richiesta, declassato a Revisione in modalità base64. Una scrittura su file in sospeso si presenta come una sfida di approvazione, che il ciclo di gestione degli errori deve trattare come una pausa, non come un guasto (livelli di rischio HITL).

Envelope JSON del gate di conferma

Un’approvazione in sospeso restituisce:

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

Richiamare lo stesso strumento con _confirmation_token impostato su quel token: la risposta restituisce { "allowed": true }. Per il flusso completo, vedere output-approval.