좋은 에러 메시지를 만드는 6가지 원칙

서버에는 에러 메시지를 만들때 기본적으로 클라이언트가 이해하기 쉽도록 에러 코드 정의를 진행하고 에러 메시지를 작성합니다. 이 글은 클라이언트에서 뿐만 아닌 사용자의 관점을 중심으로 작성한 방법들에 해당되는 내용입니다. 토스의 UX Writer 님이 작성해주신 내용인데, 이러한 에러 메시지를 서버에서 핸들링하는 것도 좋은 방법일 것 같아 실례를 범하면서 퍼오게 되었습니다.

원문 글은 아래 링크에 존재합니다. 

https://toss.tech/article/how-to-write-error-message

좋은 에러 메시지를 만드는 6가지 원칙

 

---

 

1. 최고의 에러는 발생하지 않는 것

문구를 쓰기 전, 에러 메시지가 꼭 필요한지를 먼저 생각했어요. 최고의 에러는 ‘발생하지 않는 것’이니까요.

이 메시지는 연락처 송금 화면에서 내 연락처를 누르면 만나는 에러인데요. 토스에서 스스로 송금하는 건 계좌로만 가능하기 때문에, 연락처 송금을 쓸 수 없어요. 그렇다면, 사용자가 꼭 이 에러를 봐야 할까요? 처음부터 연락처 목록에 내 연락처가 뜨지 않는다면 보지 않아도 될 메시지니까요. 그래서 이 에러는 메시지를 고치는 게 아니라, 연락처 목록에서 내 연락처를 노출하지 않는 방향으로 작업했어요.

일단 에러 메시지부터 써봤는데, 다시 보니 UX를 개선하면 없어도 되는 메시지일 때가 종종 있을 거예요. 메시지를 고치기 전에 ‘이 에러가 꼭 있어야 할까?’를 한 번 더 생각해보면 좋아요.

 

2. 적절한 컴포넌트 쓰기

그 다음엔 적절한 컴포넌트를 사용했는지를 생각했어요. 예를 들어 충분히 설명이 필요한 상황인데 다이얼로그를 쓰지 않고 토스트로 짧게 전달해서 오해를 불러 일으킨다든가, 별로 위급한 상황이 아닌데 빨간색을 써서 실제보다 더 심각한 상황처럼 전달하게 된다든가 하는 문제가 생기지 않도록요.

이 메시지는 이미 심사가 시작돼서, 앱 안에서 대출을 취소할 수 없을 때 만나는 에러예요. 토스트는 3~5초 사이에 사라지는 컴포넌트인데, 너무 많은 내용이 담겨있죠. 이때 다이얼로그를 써서 유저가 처한 상황, 그 이유, 해결책을 충분히 설명했어요.

{
    "httpStatus": 200, // 에러 코드는 기본적으로 서버 에러가 아닌 런타임에러로 표기합니다.
    "errorCode": "E1011", // 에러 코드를 서버에서 따로 정의한 코드로 만들어줍니다.
    "errorPopupYn": "Y", // 에러가 팝업인지 아닌지 클라이언트에서 확인이 가능하도록 합니다.
    "errorTitle": "전화로만 취소할 수 있어요", // 팝업이 뜬다면 에러 타이틀을 설정해줍니다.
    "errorMessage": "이미 심사를 시작했어요. ...", // 팝업이 뜬다면 에러 메시지를 설정해줍니다.
    "errorNext": "전화하기", // 때에 따라 진행하는 경우 
    "errorPrev": "취소",    // 이전 단계로 돌아가는 경우
}

 

3. 스스로 해결할 수 있는 방법 알려주기

적절한 그릇(컴포넌트)을 골랐다면, 어떤 내용을 담아야 할지 고민해야겠죠. 에러 상황을 맞닥뜨렸을 때 사용자가 가장 원하는 것은 무엇일까요? 바로 다음 화면으로 넘어가는 것이겠죠. 그러려면 사용자가 스스로 에러를 해결할 수 있도록 해결책을 알려줘야 해요. 에러 메시지의 궁극적인 역할이자, 원칙들 중 가장 중요한 내용이기도 해요.

이 메시지는 지문이나 페이스 ID같은 생체 인증에 실패했을 때 만나는 에러인데요. 실패했다는 상황만 알려주고 어떻게 해야 하는지는 알려주지 않았어요. 사용자는 몇 번 반복하다 똑같은 에러를 보고선 지쳐 포기할 거예요. 개발자분께 여쭤보니 앱을 재부팅하거나 재설치하면 해결되는 문제더라고요. 그래서 해결책을 알려주기로 했죠.

 

4. 사용자 입장에서 이해할 수 있는 언어로 쓰기

공급자가 아닌 사용자의 입장에서 해결책을 전달하는 것도 중요해요.

이 메시지는 기간이 만료된 신분증을 썼을 때 만나는 에러인데요. 공급자 입장에서는 실제로 시스템에서 예외 처리된 신분증이기 때문에 알 수 없는이라는 문구를 썼지만, 사용자 입장에서는 저 문구를 이해하기가 어렵죠. 사용자가 직접 에러를 해결할 수 있도록 사용자 입장에서 이유를 이야기해줘야 해요.

 

개발자만 읽을 수 있는 코드로 된 에러나, IT 업계 용어로 이뤄진 에러도 마찬가지예요. 공급자 입장에서는 맞는 말이라도, 유저가 이해할 수 없는 문구라면 ‘그래서 유저가 이 에러를 해결하려면 어떻게 해야 하지?’를 한 번 더 생각해보면 좋아요.

 

5. 쉽게 해결할 수 있게 도와주기

해결책을 알려줬는데 그걸 수행하는 과정이 너무 지난해서 사용자가 포기한다면 큰 의미가 없겠죠. 해결 방법을 알려주는 것도 중요하지만, 그것을 최소한의 비용으로 수행할 수 있게 도와주는 것도 에러 메시지의 역할이에요.

이 메시지는 대출 신청 중간에 이탈한 분이 다시 신청하려고 할 때, 신청이 불가능하다는 것을 안내하는 에러예요. 하루에 한 번만 신청할 수 있지만, 그 날 꼭 신청해야 하는 분들은 고객센터에 따로 문의하면 처리해드릴 수 있는 상황이었어요.

‘고객센터로 문의해달라’고 문구를 남겨뒀지만, 사용자는 앱을 떠나 전화번호를 누르거나, 토스 앱 안에서 고객센터가 어디있는지 직접 찾아야했죠. 그런 사용자의 수고를 덜기 위해, 탭 한 번으로 문의할 수 있도록 버튼을 추가했어요.

 

6. 부정적인 감정 최소화하기

위의 것들을 다 지키면 우리는 최선을 다한 게 맞지만, 그럼에도 사용자는 원래 기대했던 화면을 보지 못한 것이 맞잖아요. 크든 작든 좌절할 수밖에 없는 상황이니, 최대한 그 감정을 배려하여 커뮤니케이션해야 해요.

에러 메시지가 주로 ‘안 돼요’, ‘없어요’ 같은 문장이 많잖아요. 부정형 문장을 최대한 긍정형으로 전달하기 위해, 안되는 사실을 전달하는 것보다 할 수 있는 것들을 이야기하는 방식을 선택했어요. 사용자의 선택권을 존중하기 위해 ~해야 해요라고 강요하는 듯한 말투보다, ~할 수 있어요라고 권유하는 말투를 쓰기도 하고요.

에러 메시지를 써야 한다면,
이 원칙들을 체크리스트처럼 차례로 확인하면서 작성해보세요!

1. 최고의 에러는 발생하지 않는 것
2. 적절한 컴포넌트 쓰기
3. 스스로 해결할 수 있는 방법 알려주기
4. 사용자 입장에서 이해할 수 있는 언어로 쓰기
5. 쉽게 해결할 수 있게 도와주기
6. 부정적인 감정 최소화하기