GraphQL 에러, 어떻게 처리할까? 카카오스타일의 노하우 공개!

GraphQL 에러 응답 형식의 이해 부족으로 API 설계 실수가 발생했음

errors 배열을 활용하여 에러 메시지, 코드, 추가 정보를 전달함

HTTP 상태 코드 대신 errors 필드를 활용하는 방식으로 에러 처리

GraphQL 에러 응답 구조

GraphQL은 data와 errors 필드를 사용하여 에러를 처리한다. errors 배열은 여러 에러 상황을 효과적으로 관리하며, 각 에러는 message, locations, path 정보를 포함한다. 따라서, API 설계 시 errors 배열의 중요성을 인지하고, 적절한 에러 처리 로직을 구현해야 한다.

에러 메시지 관리: 서버 vs 클라이언트

서버는 사용자 친화적인 에러 메시지를 관리하고, 클라이언트는 이를 표시하는 역할을 수행한다. 다국어 지원을 위해 서버는 클라이언트의 언어 정보를 받아 에러 메시지를 구성해야 한다. 에러 코드를 함께 전송하여 클라이언트가 특정 상황에 대한 맞춤형 처리를 가능하게 한다.

HTTP 상태 코드 활용의 딜레마

GraphQL은 HTTP 상태 코드 사용에 대한 명확한 지침이 없다. 카카오스타일은 200 OK 상태 코드를 반환하고, errors 필드를 통해 비즈니스 로직 실패를 처리한다. HTTP 상태 코드에 의존하지 않는 클라이언트 구현은 유연성을 확보하고, 향후 스펙 변경에 대응할 수 있도록 한다.