초보 사용자가 다음 행동을 알 수 있는 오류 문장 쓰기

바이브코딩으로 입력 폼이나 파일 변환 도구를 만들면 정상 화면은 금방 완성됩니다. 막상 서비스가 불편해지는 순간은 값이 비었거나, 파일 형식이 다르거나, 서버가 잠시 멈췄을 때입니다. 화면에 “오류가 발생했습니다”만 뜨면 사용자는 자기 실수인지 서비스 문제인지도 알 수 없습니다.

오류 메시지는 개발자 로그를 줄여 보여 주는 칸이 아닙니다. 길을 잘못 든 사람에게 현재 위치와 돌아갈 방향을 알려 주는 안내판에 가깝습니다. 무엇이 잘못됐고 어디를 고치며 다음에 어떤 결과가 생기는지 설명해야 사용자가 스스로 복구할 수 있습니다.

한 문장에 문제와 대상과 다음 행동을 담는다

오류 문장은 먼저 문제가 생긴 대상을 부릅니다. “입력 오류”보다 “이메일 주소를 입력하세요”가 구체적입니다. 형식이 다르면 기대하는 규칙을 말하고, 범위가 넘으면 허용 범위를 알려 줍니다. 개발 용어인 validation은 입력값이 서비스 규칙에 맞는지 확인하는 과정이라는 뜻입니다.

다음 두 문장을 비교해 보세요.

나쁜 예: 유효하지 않은 값입니다.
나은 예: 이메일 주소에 @ 뒤의 도메인을 입력하세요.

두 번째 문장은 어느 칸에 무엇이 빠졌는지와 고칠 행동을 함께 말합니다. “잘못 입력했습니다”처럼 사용자를 탓하지 않고 화면이 요구하는 조건을 주어로 씁니다. 해결 방법을 모르는 서버 장애라면 재입력하라고 반복시키지 말고 나중에 다시 시도할 시점이나 문의 경로를 안내합니다.

사용자 입력과 서비스 실패를 같은 문장으로 다루지 않는다

입력 오류는 사용자가 값을 고쳐 계속할 수 있는 상황입니다. 서버 오류, 네트워크 끊김, 저장 공간 부족은 사용자가 같은 값을 다시 써도 해결되지 않을 수 있습니다. GOV.UK 디자인 시스템도 사용자가 고칠 수 없는 서비스 문제를 일반 입력 오류 메시지로 다루지 말고 별도 설명과 다음 행동을 제공하라고 안내합니다.

식당 주문에 비유하면 “테이블 번호를 입력하세요”는 손님이 고칠 수 있지만 “주방 주문 시스템이 연결되지 않았습니다”는 직원이 복구해야 합니다. 두 상황 모두 빨간 글씨 한 줄로 처리하면 손님은 같은 입력을 반복하고 자료가 중복 전송될 수 있습니다.

• 빈 값과 형식 오류는 해당 입력칸에서 고치게 합니다.
• 권한 부족은 필요한 계정이나 담당자 확인 방법을 안내합니다.
• 네트워크 실패는 입력을 보존하고 재시도 가능 여부를 말합니다.
• 서버 장애는 사용자 탓이 아님을 분명히 하고 문의 기준을 줍니다.
• 결제 결과가 불확실하면 다시 결제시키지 말고 거래 상태 확인으로 보냅니다.

오류를 입력칸 가까이 두고 위에서도 찾게 한다

긴 폼에서는 오류를 화면 위에만 모으면 어느 칸을 고쳐야 하는지 찾기 어렵습니다. 입력칸 가까이에 같은 오류 문장을 표시하고, 여러 오류가 있다면 페이지 위 요약에서 해당 칸으로 이동할 수 있게 연결합니다. 사용자가 입력한 정상 값과 수정할 값을 지우지 않는 것도 중요합니다.

W3C의 WCAG 2.2 설명은 자동으로 감지한 입력 오류의 항목을 식별하고 오류를 텍스트로 설명해야 한다고 밝힙니다. WCAG는 웹 콘텐츠 접근성 지침으로, 장애가 있는 사람을 포함해 더 많은 사용자가 웹을 이용할 수 있게 하는 기준입니다. 빨간 테두리만으로는 색을 구분하기 어려운 사용자나 화면 읽기 도구 사용자에게 오류를 충분히 전달하지 못합니다.

색과 아이콘에 텍스트 설명을 더한다

오류 상태에 빨간색과 경고 아이콘을 쓰는 것은 도움이 될 수 있지만 그것만 써서는 안 됩니다. 입력칸 이름과 오류 내용을 텍스트로 적고, 보조 기술이 읽을 수 있도록 연결해야 합니다. 스크린 리더는 화면의 글과 구조를 음성이나 점자로 전달하는 도구입니다.

폼 제출 뒤 화면이 그대로라면 사용자는 실패 사실을 놓칠 수 있습니다. 오류 요약에 초점을 옮기거나 상태 변화를 알리는 방식을 검토하되, 갑작스러운 이동이 현재 입력을 잃게 해서는 안 됩니다. 모바일에서는 키보드가 열린 상태에서도 오류 문장이 입력칸과 버튼을 가리지 않는지 확인합니다.

입력값을 지우지 않아야 복구 비용이 줄어든다

오류가 하나 생겼다고 이름, 주소, 긴 설명을 모두 지우면 사용자는 같은 일을 반복해야 합니다. GOV.UK 안내도 통과한 답과 실패한 답을 유지해 사용자가 무엇이 잘못됐는지 보고 이전 값을 고칠 수 있게 하라고 설명합니다.

다만 비밀번호와 카드 보안 번호처럼 보존 방식에 민감한 값은 별도 보안 기준을 따릅니다. 브라우저나 서버 로그에 원문을 남기지 않고, 화면에 다시 표시하지 않는 이유를 안내할 수 있습니다. 편의를 위해 민감한 값을 localStorage나 오류 추적 서비스에 저장하지 않습니다.

내부 오류와 사용자 메시지는 층을 나눈다

개발자에게는 요청 ID, 실패 위치, 상태 코드, 재현 정보가 필요할 수 있습니다. 사용자에게는 해결 가능한 쉬운 문장이 필요합니다. 두 메시지를 분리하면 내부 데이터베이스 이름, 서버 경로, 접근 토큰 같은 정보가 화면에 노출되는 일을 줄일 수 있습니다.

“SQLSTATE 23505”를 그대로 보여 주기보다 “이미 등록된 이메일입니다. 로그인하거나 다른 이메일을 입력하세요”라고 바꿉니다. 개발 로그에는 민감정보를 제거한 오류 코드와 요청 ID를 남깁니다. 사용자가 문의할 때 요청 ID를 전달하면 운영자가 원인을 찾을 수 있지만, 전체 로그나 비밀키를 보내게 해서는 안 됩니다.

결제와 삭제 오류에는 중복 행동을 막는 문장이 필요하다

결제 버튼을 눌렀는데 응답이 늦으면 사용자는 다시 누르기 쉽습니다. 이때 “실패했습니다. 다시 시도하세요”라고 단정하면 실제 승인된 결제가 중복될 수 있습니다. 먼저 주문 또는 결제 상태를 확인하고, 결과를 확인할 수 없으면 추가 결제를 막은 채 조회나 고객 지원으로 안내합니다.

삭제도 비슷합니다. 일부만 삭제됐는지, 취소 가능한지, 복구 시간이 있는지 구분합니다. 사용자 메시지에서 성공하지 않은 작업을 성공했다고 말하지 않습니다. 운영 로그와 실제 저장 상태를 확인하기 전에는 완료, 환불, 삭제됨 같은 단어를 쓰지 않습니다.

오류 문장 표를 만들어 같은 상황을 일관되게 다룬다

기능마다 즉석에서 문장을 만들면 같은 오류가 화면마다 다르게 보입니다. 오류 종류, 사용자 문장, 다음 행동, 보존할 입력, 로그 코드 다섯 칸으로 작은 표를 만드세요. 고객 지원 문구와 제품 화면이 같은 상태 이름을 쓰는지도 확인합니다.

문장을 소리 내어 읽으면 책임을 떠넘기거나 번역투인 표현을 쉽게 찾을 수 있습니다. “요청이 정상적으로 처리되지 못하였습니다”보다 “파일을 저장하지 못했습니다. 인터넷 연결을 확인한 뒤 다시 시도하세요”가 짧고 행동이 분명합니다. 원인을 확실히 모르면 추측하지 말고 확인 가능한 범위만 말합니다.

오늘 바로 해볼 작은 실습

서비스에서 “오류가 발생했습니다”라는 문장 하나를 골라 바꿔 봅니다.

1. 실패한 대상이 입력, 파일, 저장, 결제 중 무엇인지 적습니다.
2. 사용자가 고칠 수 있는 문제인지 서비스 문제인지 나눕니다.
3. 문제와 대상과 다음 행동을 한 문장으로 씁니다.
4. 입력값이 오류 뒤에도 남는지 확인합니다.
5. 빨간색을 보지 않아도 텍스트만으로 뜻이 통하는지 읽습니다.
6. 모바일과 화면 읽기 도구에서 오류 위치를 확인합니다.
7. 로그에 비밀번호, 카드번호, API 키가 남지 않는지 점검합니다.

모르는 오류를 해결하려고 데이터 삭제, 강제 재시도, 중복 결제를 실행하지 마세요. 사용자 화면에는 내부 경로와 비밀값을 숨기고, 운영자에게는 민감정보를 제거한 요청 ID와 상태를 남깁니다. 좋은 오류 문장은 실패를 감추는 장식이 아니라 사용자가 안전하게 다음 단계로 이동하게 하는 제품 기능입니다.