NextPDF Connect 워크플로에서 오류 처리하기

한눈에 보기

복원력 있는 Connect 워크플로를 구축합니다. 모든 도구 결과를 검증하고, 실패한 세션을 폐기한 뒤, 새로운 상태로 재시도합니다. 실패한 도구는 구조화된 오류 결과를 반환하며, 이는 전송 실패가 아니라 정상적인 응답입니다. PSR-18도 같은 구분을 합니다. 상태가 오류를 나타내더라도 응답은 반환됩니다(PSR-18 §3).

설치

composer require nextpdf/server

전송을 바인딩합니다. 이 레시피는 create_pdf, add_text, output_pdf를 사용하며, 이들은 모두 Core입니다.

개념 개요

실패한 도구 호출은 오류 결과를 반환합니다. 오류 결과에는 오류 플래그와 사람이 읽을 수 있는 메시지가 담기며, 해당하는 경우 코드도 포함됩니다. 성공한 결과에는 오류 플래그가 없으며 도구의 정상 출력이 담깁니다. 어느 쪽이든 전송은 요청을 보내고 응답을 받았습니다(PSR-18 §p2).

방어적 루프는 짧습니다. 호출을 보내고 결과를 읽습니다. 오류라면 기록하고, 분류한 뒤, 복구 전략을 적용하며, 오래된 상태로 진행하지 않습니다. 그렇지 않다면 필요한 필드를 추출하고 계속합니다.

API 표면

도구	역할	위험 등급
`create_pdf`	세션 열기	안전
`add_text`	텍스트 쓰기	주의
`output_pdf`	PDF 렌더링 및 반환	승인 필요 / 검토(base64)

도구 카탈로그가 기준 카탈로그입니다. 사용 가능한 도구는 설치된 등급에 따라 달라집니다.

코드 샘플 — 빠른 시작

정상 경로(create_pdf → add_text → output_pdf)를 실행하고 각 결과를 확인합니다. 그런 다음 세션 오류를 유발하기 위해 의도적으로 폐기된 document_id를 add_text에서 재사용합니다. 새 세션을 만들고 콘텐츠를 다시 재생하여 복구합니다.

코드 샘플 — 프로덕션

오류를 범주별로 분류하고 그에 맞게 대응합니다.

입력 검증 — 결정적입니다. 인수를 수정하고 같은 호출을 재시도합니다. 예: 빈 텍스트, 잘못된 정렬, 양수가 아닌 크기, 알 수 없는 페이지 크기, 알 수 없는 글꼴 패밀리.
세션 — document_id가 더 이상 존재하지 않습니다. 새 세션을 만들고 모든 콘텐츠를 다시 재생합니다.
시스템 — 세션 한도와 같은 서버 리소스 제약입니다. 백오프 후 재시도합니다.
승인 — 파일로 내보내는 output_pdf는 사람의 승인을 위해 일시 중지될 수 있습니다. 이는 실패가 아니라 워크플로 일시 중지입니다. 챌린지를 전달하고 기다린 다음, 확인 토큰과 함께 다시 호출합니다.

성공을 결코 가정하지 말고, 세션 오류 후에는 document_id를 결코 재사용하지 말며, 모든 콘텐츠 단계가 성공하기 전에는 output_pdf를 결코 보내지 마십시오.

엣지 케이스 & 주의사항

승인은 오류가 아닙니다. HITL 챌린지는 일시 중지입니다. 촘촘한 루프에서 재시도하지 마십시오. 사람에게 전달하십시오.
서버 재시작. 메모리 내 모든 세션이 지워지며, 이전의 모든 document_id가 무효화됩니다.
부분 워크플로. add_text가 문서 중간에 실패하면 세션이 일관되지 않을 수 있습니다. 안전한 복구 방법은 부분 수리가 아니라 새 세션을 만드는 것입니다.

성능

무시할 만합니다. 이 레시피는 렌더링이 아니라 제어 흐름에 관한 것입니다. 생성되는 모든 출력의 프로필은 structural입니다.

보안 참고사항

오류 메시지는 호출하는 에이전트와 운영자를 위한 것입니다. 원시 서버 오류 텍스트를 신뢰할 수 없는 최종 사용자에게 그대로 노출하지 마십시오. 대신 분류하고 정제한 메시지를 표시하십시오.

적합성

진술	스펙	절	reference_id
전송은 결과와 관계없이 응답을 반환합니다.	PSR-18	§p2
오류 상태에서도 응답이 반환됩니다.	PSR-18	§3

상업적 맥락

해당 없음 — 모든 도구가 Core 입니다.

전송 가용성

전송	사용 가능	참고
MCP(stdio)	예	오류는 오류 플래그가 있는 도구 결과로 도착합니다.
REST	예	2xx가 아닌 상태는 동일하게 분류된 오류 본문을 담습니다.
gRPC	예	상태 코드와 오류 결과 메시지.

모든 전송에서 도구 수준 오류는 검사해야 할 정상적인 응답이지, 누락된 호출이 아닙니다(PSR-18 §3).

HITL 위험 등급

create_pdf는 Safe, add_text는 Caution, output_pdf는 Approval Required이며, base64 모드에서는 Review로 강등됩니다. 대기 중인 파일 쓰기는 승인 챌린지로 표시되며, 오류 루프는 이를 실패가 아니라 일시 중지로 취급해야 합니다(HITL 위험 등급).

확인 게이트 JSON 엔벨로프

대기 중인 승인은 다음을 반환합니다.

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

같은 도구를 다시 호출하면서 _confirmation_token을 해당 토큰으로 설정하면 { "allowed": true }를 반환합니다. 전체 흐름은 output-approval을 참조하십시오.