Gestión de errores en flujos de trabajo de NextPDF Connect

Visión general

Crear flujos de trabajo de Connect resilientes implica validar cada resultado de herramienta, descartar una sesión fallida y reintentar con un estado nuevo. Una herramienta que falla devuelve un resultado de error estructurado; es una respuesta normal, no un fallo de transporte. PSR-18 mantiene la misma distinción: se devuelve una respuesta incluso cuando el estado indica un error (PSR-18 §3).

Instalación

composer require nextpdf/server

Vincular un transporte. Esta receta utiliza create_pdf, add_text y output_pdf; todas pertenecen a Core.

Visión general conceptual

Una llamada fallida a una herramienta devuelve un resultado de error. Incluye un indicador de error y un mensaje legible para humanos, con un código cuando corresponda. Un resultado correcto no contiene un indicador de error e incluye la salida normal de la herramienta. En ambos casos, el transporte envió la solicitud y recibió la respuesta (PSR-18 §p2).

El bucle defensivo es breve. Enviar la llamada y leer el resultado. Si es un error, registrarlo, clasificarlo, aplicar la estrategia de recuperación y no continuar con un estado obsoleto. De lo contrario, extraer los campos necesarios y continuar.

Superficie de la API

Herramienta	Función	Nivel de riesgo
`create_pdf`	Abrir la sesión	Seguro
`add_text`	Escribir texto	Precaución
`output_pdf`	Representar y devolver el PDF	Aprobación obligatoria / Revisión (base64)

El catálogo de herramientas es la referencia principal. Las herramientas disponibles dependen de la edición instalada.

Ejemplo de código — Inicio rápido

Ejecutar la ruta correcta (create_pdf → add_text → output_pdf) y comprobar cada resultado. A continuación, reutilizar a propósito un document_id destruido en add_text para provocar un error de sesión. Recuperarse creando una nueva sesión y reproduciendo el contenido.

Ejemplo de código — Producción

Clasificar los errores por categoría y responder en consecuencia:

Validación de entrada — determinista. Corregir los argumentos y reintentar la misma llamada. Ejemplos: texto vacío, alineación no válida, tamaño no positivo, tamaño de página desconocido, familia de fuentes desconocida.
Sesión — el document_id ya no existe. Crear una nueva sesión y reproducir todo el contenido.
Sistema — una restricción de recursos del servidor, como el límite de sesiones. Esperar un tiempo y reintentar.
Aprobación — al escribir con output_pdf en un archivo, el flujo puede pausarse para aprobación humana. Esto es una pausa del flujo de trabajo, no un fallo. Transmitir el desafío y esperar; después, volver a llamar con el token de confirmación.

Nunca dar por hecho el éxito; nunca reutilizar un document_id tras un error de sesión; nunca enviar output_pdf hasta que cada paso de contenido se haya completado correctamente.

Casos límite y problemas comunes

La aprobación no es un error. El desafío HITL es una pausa. No reintentar en un bucle cerrado. Transmitirlo a la persona.
Reinicio del servidor. Todas las sesiones en memoria se eliminan y cada document_id anterior deja de ser válido.
Flujo de trabajo parcial. Si add_text falla a mitad del documento, la sesión puede quedar inconsistente. La recuperación segura es crear una sesión nueva, no hacer una reparación parcial.

Rendimiento

Insignificante. Esta receta aborda el flujo de control, no la representación. El perfil es structural para cualquier salida producida.

Notas de seguridad

Los mensajes de error están destinados al agente que realiza la llamada y al operador. No reproducir textualmente ante usuarios finales no confiables el texto de error sin procesar del servidor. En su lugar, mostrar un mensaje clasificado y depurado.

Conformidad

Declaración	Especificación	Cláusula	reference_id
El transporte devuelve una respuesta independientemente del resultado.	PSR-18	§p2
Se devuelve una respuesta incluso ante un estado de error.	PSR-18	§3

Contexto comercial

No aplicable — todas las herramientas son Core.

Disponibilidad del transporte

Transporte	Disponible	Notas
MCP (stdio)	Sí	Los errores llegan como un resultado de herramienta con un indicador de error.
REST	Sí	Un estado distinto de 2xx incluye el mismo cuerpo de error clasificado.
gRPC	Sí	Un código de estado junto con un mensaje de resultado de error.

En todos los transportes, un error a nivel de herramienta es una respuesta normal que debe inspeccionarse, no una llamada perdida (PSR-18 §3).

Nivel de riesgo HITL

create_pdf es Seguro, add_text es Precaución y output_pdf es Aprobación obligatoria, rebajado a Revisión en modo base64. Una escritura de archivo pendiente se presenta como el desafío de aprobación, que el bucle de gestión de errores debe tratar como una pausa, no como un fallo (niveles de riesgo HITL).

Sobre el JSON de la puerta de confirmación

Una aprobación pendiente devuelve:

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

Volver a llamar a la misma herramienta con _confirmation_token establecido en ese token; la llamada devuelve { "allowed": true }. Para ver el flujo completo, consultar output-approval.