Trate erros em fluxos de trabalho do NextPDF Connect

Visão geral

Crie fluxos de trabalho resilientes no Connect. Valide cada resultado de ferramenta, encerre a sessão com falha e tente novamente a partir de um estado limpo. Quando uma ferramenta falha, ela retorna um resultado de erro estruturado. Trate esse resultado como resposta normal, não como falha de transporte. A PHP Standards Recommendation (PSR)-18 faz a mesma distinção: uma resposta é retornada mesmo quando o status indica erro (PSR-18 §3).

Instalação

composer require nextpdf/server

Vincule um transporte. Esta receita usa create_pdf, add_text e output_pdf. Todas as três ferramentas são Core.

Visão conceitual

Quando uma chamada de ferramenta falha, ela retorna um resultado de erro. O resultado traz um sinalizador de erro, uma mensagem legível para humanos e um código quando aplicável. Um resultado bem-sucedido não contém sinalizador de erro e traz a saída normal da ferramenta. Em ambos os casos, o transporte enviou a requisição e recebeu a resposta (PSR-18 §p2).

Mantenha o laço defensivo enxuto. Envie a chamada e, em seguida, leia o resultado. Se o resultado for um erro, registre-o, classifique-o, aplique a estratégia de recuperação e pare de usar o estado desatualizado. Caso contrário, extraia os campos necessários e continue.

Superfície da API

Ferramenta	Função	Nível de risco
`create_pdf`	Abre a sessão	Seguro
`add_text`	Escreve texto	Cuidado
`output_pdf`	Renderiza e retorna o PDF	Aprovação Obrigatória / Revisão (base64)

O catálogo de ferramentas é a fonte da verdade. As ferramentas disponíveis variam conforme o tier instalado.

Exemplo de código — Início rápido

Execute o caminho feliz (create_pdf → add_text → output_pdf) e verifique cada resultado. Em seguida, reutilize intencionalmente um document_id destruído em add_text para disparar um erro de sessão. Recupere-se criando uma nova sessão e reaplicando o conteúdo.

Exemplo de código — Produção

Classifique os erros por categoria e responda de acordo:

Validação de entrada — determinística. Corrija os argumentos e, em seguida, tente novamente a mesma chamada. Exemplos: texto vazio, alinhamento inválido, tamanho não positivo, tamanho de página desconhecido, família de fonte desconhecida.
Sessão — o document_id não existe mais. Crie uma nova sessão e, em seguida, reaplique todo o conteúdo.
Sistema — uma restrição de recursos no servidor, como o limite de sessões. Aplique backoff e, em seguida, tente novamente.
Aprovação — output_pdf para um arquivo pode pausar para aprovação humana. Isso é uma pausa no fluxo de trabalho, não uma falha. Encaminhe o desafio e aguarde; em seguida, chame novamente com o token de confirmação.

Nunca presuma que deu certo. Nunca reutilize um document_id após um erro de sessão. Nunca envie output_pdf antes que cada etapa de conteúdo tenha sido concluída com sucesso.

Casos extremos e armadilhas

Aprovação não é um erro. O desafio human-in-the-loop (HITL) é uma pausa. Não tente novamente em um loop apertado. Encaminhe-o ao humano responsável.
Reinicialização do servidor. Todas as sessões em memória são limpas, e cada document_id anterior se torna inválido.
Fluxo de trabalho parcial. Se add_text falhar no meio do documento, a sessão pode ficar inconsistente. A recuperação segura é uma nova sessão, não um reparo parcial.

Desempenho

Impacto desprezível. Esta receita trata do fluxo de controle, não da renderização. O perfil é structural para qualquer saída produzida.

Notas de segurança

As mensagens de erro são destinadas ao agente chamador e ao operador. Não repasse literalmente o texto bruto do erro do servidor para usuários finais não confiáveis. Em vez disso, exiba uma mensagem classificada e sanitizada.

Conformidade

Declaração	Especificação	Cláusula	reference_id
O transporte retorna uma resposta independentemente do resultado.	PSR-18	§p2
Uma resposta é retornada mesmo quando o status é de erro.	PSR-18	§3

Contexto comercial

Não aplicável — todas as ferramentas são Core.

Disponibilidade de transporte

Transporte	Disponível	Observações
MCP (stdio)	Sim	Os erros chegam como resultado de ferramenta com um sinalizador de erro.
REST	Sim	Um status diferente de 2xx carrega o mesmo corpo de erro classificado.
gRPC	Sim	Um código de status acompanhado de uma mensagem de resultado de erro.

Em todos os transportes, inspecione um erro no nível da ferramenta como resposta normal, não como chamada perdida (PSR-18 §3).

Nível de risco HITL

create_pdf é Seguro, add_text é Cuidado e output_pdf é Aprovação Obrigatória, rebaixado para Revisão no modo base64. Uma escrita de arquivo pendente aparece como um desafio de aprovação. O tratamento de erro deve tratá-lo como uma pausa, não como uma falha (níveis de risco HITL).

Envelope JSON do portão de confirmação

Uma aprovação pendente retorna:

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

Chame novamente a mesma ferramenta com _confirmation_token definido para esse token. Ela retorna { "allowed": true }. Para o fluxo completo, consulte output-approval.