Gérer les erreurs dans un flux de travail NextPDF Connect

En un coup d’œil

Construis des flux de travail Connect résilients. Valide chaque résultat d’outil, mets fin à toute session en échec et réessaie avec un état neuf. Un outil qui échoue renvoie un résultat d’erreur structuré : il s’agit d’une réponse normale, pas d’une défaillance du transport. PSR-18 opère la même distinction : une réponse est renvoyée même lorsque le statut indique une erreur (PSR-18 §3).

Installation

composer require nextpdf/server

Configure un transport. Cette recette utilise create_pdf, add_text et output_pdf, qui relèvent tous de Core.

Vue d’ensemble conceptuelle

Un appel d’outil en échec renvoie un résultat d’erreur. Il contient un indicateur d’erreur et un message lisible par un humain, avec, le cas échéant, un code. Un résultat réussi n’a aucun indicateur d’erreur et contient la sortie normale de l’outil. Dans les deux cas, le transport a envoyé la requête et reçu la réponse (PSR-18 §p2).

Le schéma défensif est simple. Envoie l’appel et lis le résultat. S’il s’agit d’une erreur, journalise-la, classe-la, applique la stratégie de récupération et ne continue pas avec un état périmé. Sinon, extrais les champs dont tu as besoin et poursuis.

Surface de l’API

Outil	Rôle	Niveau de risque
`create_pdf`	Ouvrir la session	Sûr
`add_text`	Écrire du texte	Prudence
`output_pdf`	Effectuer le rendu et renvoyer le PDF	Approbation requise / Examen (base64)

Le catalogue d’outils constitue la référence. Les outils disponibles dépendent du palier installé.

Exemple de code — Démarrage rapide

Exécute le chemin nominal (create_pdf → add_text → output_pdf) et vérifie chaque résultat. Réutilise ensuite volontairement un document_id détruit avec add_text pour déclencher une erreur de session. Reprends en créant une nouvelle session et en rejouant le contenu.

Exemple de code — Production

Classe les erreurs par catégorie et réagis en conséquence :

Validation des entrées — déterministe. Corrige les arguments et réessaie le même appel. Exemples : texte vide, alignement non valide, taille non positive, format de page inconnu, famille de police inconnue.
Session — le document_id n’existe plus. Crée une nouvelle session et rejoue tout le contenu.
Système — une contrainte de ressource serveur, comme la limite de sessions. Patiente, puis réessaie.
Approbation — output_pdf vers un fichier peut être mis en pause pour une approbation humaine. C’est une pause du flux de travail, pas une défaillance. Transmets le défi et attends, puis rappelle avec le jeton de confirmation.

Ne pars jamais du principe que l’appel a réussi ; ne réutilise jamais un document_id après une erreur de session ; n’envoie jamais output_pdf tant que chaque étape de contenu n’a pas réussi.

Cas limites & pièges

L’approbation n’est pas une erreur. Le défi HITL est une pause. Ne réessaie pas dans une boucle serrée. Transmets-le à l’humain.
Redémarrage du serveur. Toutes les sessions en mémoire sont effacées, et chaque document_id antérieur devient non valide.
Flux de travail partiel. Si add_text échoue en milieu de document, la session peut être incohérente. La récupération sûre consiste à repartir d’une nouvelle session, pas à tenter une réparation partielle.

Performances

L’impact est négligeable. Cette recette porte sur le flux de contrôle, pas sur le rendu. Le profil est structural pour toute sortie produite.

Notes de sécurité

Les messages d’erreur sont destinés à l’agent appelant et à l’opérateur. Ne renvoie pas tel quel le message d’erreur brut du serveur à des utilisateurs finaux non fiables. Présente plutôt un message classé et assaini.

Conformité

Énoncé	Spécification	Clause	reference_id
Le transport renvoie une réponse quel que soit le résultat.	PSR-18	§p2
Une réponse est renvoyée même en cas de statut d’erreur.	PSR-18	§3

Contexte commercial

Sans objet — tous les outils relèvent de Core.

Disponibilité du transport

Transport	Disponible	Notes
MCP (stdio)	Oui	Les erreurs arrivent sous la forme d’un résultat d’outil avec un indicateur d’erreur.
REST	Oui	Un statut non 2xx transporte le même corps d’erreur classé.
gRPC	Oui	Un code de statut accompagné d’un message de résultat d’erreur.

Quel que soit le transport, une erreur au niveau de l’outil est une réponse normale à inspecter, pas un appel perdu (PSR-18 §3).

Niveau de risque HITL

create_pdf est Sûr, add_text est Prudence, et output_pdf est Approbation requise, rétrogradé à Examen en mode base64. Une écriture de fichier en attente se présente comme un défi d’approbation, que la boucle de gestion des erreurs doit traiter comme une pause, pas comme une défaillance (niveaux de risque HITL).

Enveloppe JSON du verrou de confirmation

Une approbation en attente renvoie :

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

Rappelle le même outil avec _confirmation_token défini sur ce jeton, et il renvoie { "allowed": true }. Pour le déroulé complet, consulte output-approval.