🌿 중급 백엔드
API 에러 메시지는 어떻게 써야 하나요?
쉽게 이해하기
길을 물었는데 '안 돼요'라고만 대답하면 당황스럽죠. '이 길은 공사 중이라 3번 출구로 가세요'라고 구체적으로 알려줘야 도움이 돼요. API 에러 메시지도 '뭐가 잘못됐고, 어떻게 고치면 되는지' 명확히 알려줘야 합니다.
핵심 정리
사용자와 개발자가 문제를 쉽게 이해하고 해결할 수 있도록 작성하는 에러 메시지입니다.
자세히 알아보기
API 에러 메시지는 요청이 실패했을 때 사용자나 개발자에게 무엇이 잘못됐는지 알려주는 텍스트예요. 잘 작성된 에러 메시지는 문제 해결 시간을 크게 줄여줍니다.
좋은 에러 메시지는 세 가지 요소를 포함해요. 첫째, 무엇이 잘못됐는지(What), 둘째, 왜 실패했는지(Why), 셋째, 어떻게 고칠 수 있는지(How)예요. 예를 들어 '잘못된 요청'보다는 '이메일 형식이 올바르지 않습니다. @를 포함한 유효한 이메일을 입력하세요'가 훨씬 유용하죠.
에러 메시지는 사용자용과 개발자용으로 나눠서 제공하는 게 좋아요. 사용자에게는 친절하고 간단한 메시지를, 개발자에게는 상세한 기술 정보를 줍니다. JSON 응답에서 `message`는 사용자용, `error_code`와 `details`는 개발자용으로 구분할 수 있어요. 예: `{"message": "로그인에 실패했습니다", "error_code": "AUTH_001", "details": "Invalid password"}`
에러 코드를 함께 제공하면 디버깅이 쉬워져요. AUTH_001, PAYMENT_002처럼 카테고리와 번호를 조합한 코드를 만들면, 로그에서 같은 종류의 에러를 빠르게 찾을 수 있습니다. 또한 문서화할 때도 각 에러 코드의 의미와 해결 방법을 정리할 수 있어요.
절대 하지 말아야 할 것은 기술적인 스택 트레이스를 그대로 노출하는 거예요. 보안상 위험하고 사용자에게 혼란만 줍니다. 대신 서버 로그에는 상세히 기록하고, 클라이언트에는 필요한 정보만 전달하세요. 좋은 에러 메시지는 사용자 경험을 개선하고 고객 지원 비용을 줄여줍니다.