Inspekt이 API 프록시로 실패한 요청을 가로채서 LLM 기반 진단을 JSON 응답에 주입하는 방식으로 4xx 에러를 인간이 읽을 수 있는 형태로 변환

Context

422 Unprocessable Entity 같은 API 에러 응답이 개발자에게 실제 문제의 원인과 해결 방법을 명확히 전달하지 못하고 있었다.

Technical Solution

• API 요청을 직접 대상 서버로 보내는 대신 Inspekt 프록시를 거쳐 라우팅: 클라이언트 → Inspekt 프록시 → 대상 API
• 성공 응답은 그대로 통과: 프록시가 2xx 상태 코드를 감지하면 변조 없이 클라이언트로 전달
• 실패 응답 감지 시 LLM 진단 추가: 4xx/5xx 에러 발생 시 OpenAI SDK를 사용해 에러 원인 분석 및 해결책 생성
• 응답에 _diagnosis 필드 삽입: 생성된 AI 진단 결과를 JSON 응답 본문에 추가 필드로 포함
• Next.js App Router로 랜딩 페이지 및 대시보드 구현: 웹 인터페이스 제공
• Vercel Edge Runtime으로 프록시 배포: 저 레이턴시 요청 처리
• TypeScript 사용: 전체 스택에서 타입 안정성 확보

Key Takeaway

헤드리스 프록시 패턴과 LLM을 결합하면 기존 API 변경 없이 에러 응답의 이해도를 크게 향상시킬 수 있으며, 이는 개발자 경험 개선의 새로운 접근 방식을 제시한다.