요청과 응답
"요청이 실패했습니다"를 만났을 때, 내가 보낸 주문서가 어디까지 갔고 어디서 막혔는지 네 구간으로 나눠 보는 눈이에요. 돌아온 답장에 찍힌 세 자리 숫자가 누구 쪽 사정인지까지 알려줘요.
쉽게 말하면
관공서 창구를 떠올려 보세요. 서류를 받으려면 신청서 한 장을 창구에 밀어 넣고, 창구 안쪽에서 처리한 뒤 종이 한 장을 돌려받아요. 인터넷에서 벌어지는 일이 이것과 똑같아요. 손님이 버튼을 누르면 화면이 신청서 한 장을 만들어 보내고(요청), 저쪽에서 처리한 결과를 종이로 돌려줘요(응답). 그 종이 위에는 처리 결과를 뜻하는 세 자리 숫자 도장이 찍혀 있어요.
그래서 "요청이 실패했습니다"라는 문구는 생각보다 말해 주는 게 적어요. 신청서가 창구에 도착조차 못 한 것인지, 도착했는데 반려된 것인지, 처리는 됐는데 돌아오는 종이가 사라진 것인지 전부 이 한 문장으로 뭉쳐 있거든요. 셋은 고칠 자리가 완전히 다른 사고예요.
고칠 자리가 안 보여요. 코드를 처음부터 뒤지거나, 개발자에게 "안 돼요"만 전하게 돼요.
세 번만 물으면 범위가 한 구간으로 좁혀져요. AI에게 건넬 문장도 여기서 그대로 나와요.
왕복은 네 구간이에요
요청 한 번은 네 구간을 지나요. 실패는 이 중 어느 한 구간에서만 일어나요. 구간마다 증상이 다르다는 게 사장님에게 좋은 소식이에요. 증상만 보고도 어디쯤인지 짚을 수 있으니까요.
- 1내 화면(손님 휴대폰). 버튼을 누르면 여기서 신청서가 만들어져요. 이 구간에서 막히면 아무 반응도 없어요. 눌렀는데 화면이 그대로면 신청서가 출발도 못 한 거예요.
- 2가는 길(인터넷). 지하철, 지하 매장, 약한 와이파이. 이 구간에서 막히면 한참 돌다가 실패해요. 기다린 시간이 길었다는 게 단서예요.
- 3접수 창구(서버). 여기서 주소가 맞는지, 출입증이 맞는지, 양식이 맞는지 확인해요. 이 구간의 결과는 세 자리 숫자 도장으로 알려줘요.
- 4돌아온 답장. 화면이 그 종이를 읽고 손님에게 사람 말로 보여줘요. 종이는 왔는데 화면이 못 읽으면 로딩만 계속 돌거나 "알 수 없는 오류"가 떠요.
실패 문구 하나에 네 가지 사고가 섞여 있어요
그래서 "안 돼요"만으로는 아무도 못 고쳐요. 대신 세 가지만 적어 두면 사장님이 원인을 몰라도 충분해요. 몇 시에, 어느 화면에서, 얼마나 기다린 뒤에 실패했는지요. 이 셋이 구간을 거의 갈라 줘요.
답장에 찍히는 세 자리 도장
이 숫자들은 코드가 아니라 표지판이에요. 화면에 그대로 뜰 때도 있고, 개발자가 대화에서 그냥 숫자로 부를 때도 있어요. 뜻을 알면 상대가 무슨 얘기를 하는지 절반은 들려요.
| 도장 | 무슨 뜻인가 | 누구 쪽 사정인가 |
|---|---|---|
| 200 | 잘 처리됐다는 뜻이에요. 이 숫자는 화면에 안 보이고 결과만 보여요 | 아무 문제 없어요 |
| 400 | 신청서 양식이 틀렸다는 뜻이에요. 빈 칸이나 형식이 안 맞아요 | 보낸 쪽. 입력 안내 문구가 필요해요 |
| 401 | 출입증을 안 보여줬다는 뜻이에요. 로그인이 풀린 상태예요 | 보낸 쪽. 다시 로그인하면 풀려요 |
| 403 | 출입증은 있는데 이 방에 들어올 자격은 아니라는 뜻이에요 | 권한 설정. 직원 계정에서 자주 나요 |
| 404 | 그런 접수대가 없다는 뜻이에요. 주소가 틀렸거나 지운 페이지예요 | 주소 쪽. 낡은 링크에서 흔해요 |
| 429 | 너무 자주 왔으니 잠깐 줄 서라는 뜻이에요 | 횟수 한도. 손님이 몰릴 때 나요 |
| 500 | 받은 쪽 안에서 사고가 났다는 뜻이에요 | 받는 쪽. 내 서버나 거래처 안쪽이에요 |
| 502, 504 | 창구까지는 갔는데 안쪽이 답을 못 줬다는 뜻이에요 | 받는 쪽. 멈췄거나 너무 오래 걸려요 |
표를 다 외울 필요는 없어요. 규칙 한 줄만 남기면 돼요. 400번대는 보낸 쪽 사정, 500번대는 받는 쪽 사정. 이것만 알면 "내가 뭘 잘못했나"와 "저쪽이 멈췄나"가 그 자리에서 갈려요. 숫자를 하나씩 더 파고들 일이 생기면 상태 코드와 에러 읽는 법이 다음 순서예요.
숫자가 화면에 안 보일 때
요즘 화면들은 도장 숫자를 손님에게 안 보여줘요. 보기 좋게 만든 대신 단서가 사라진 거예요. 이럴 때는 "실패하면 상태 숫자를 화면 아래에 작게 남기고 기록에도 같이 남겨줘"라고 한 줄 말해 두세요. 손님은 못 알아봐도, 문의를 받은 사장님이 그 숫자 하나로 어느 쪽 사정인지 바로 갈라요.
사장님이 실제로 겪는 장면
장면 1 · 외주 개발자가 연동 문서를 보내며 말했다
“결제 요청 보내면 200이나 402가 올 수 있고, 5xx는 재시도로 처리해 뒀습니다. 타임아웃은 10초로 잡았어요.”
이제 해석돼요. 성공 도장(200)과 카드 거절 도장(402)은 화면에서 다르게 안내하고, 받는 쪽 사고(500번대)는 자동으로 다시 보내고, 10초까지만 기다리고 끊는다는 뜻이에요. 여기서 사장님이 던질 질문은 하나예요. "10초가 지나면 손님 화면에 무슨 글자가 남나요?" 이 질문에 바로 답이 나오면 실패를 다뤄 본 팀이에요.
장면 2 · 손님이 전화로 항의한다
“결제 눌렀는데 실패했다고 떴어요. 그런데 카드 결제 문자는 왔는데요?”
손님이 착각한 게 아니에요. 처리와 답장은 별개라서 생기는 일이에요. 신청서는 창구까지 갔고 결제도 됐는데, 돌아오는 종이가 도중에 끊긴 거예요. 그래서 돈은 빠졌는데 내 주문 목록에는 없어요. 이럴 때는 결제사 기록과 내 기록을 맞춰 보는 게 먼저고, 같은 신청서가 두 번 처리되지 않게 막는 장치를 개발자에게 요청해야 해요.
장면 3 · 새벽에만 주문이 안 들어왔다
“낮에는 잘 되는데 새벽 두 시부터 세 시까지 주문이 하나도 안 들어와요. 화면은 멀쩡해요.”
내 쪽 고장이 아니라 연결한 거래처가 그 시간에 점검을 하는 경우가 많아요. 택배사, 결제사, 문자 발송사는 새벽 점검 시간을 미리 공지해 두거든요. 이때 돌아오는 도장이 500번대예요. 고칠 것은 코드가 아니라 대응이에요. 실패한 주문을 버리지 말고 모아 뒀다가 점검이 끝난 뒤 다시 보내는 장치를 요청하세요. 잘 만들면 손님은 아무것도 몰라요.
증상 그대로 말하면 돼요
왼쪽에서 내 증상을 찾고, 오른쪽 문장을 AI에게 그대로 말하면 돼요. 가운데 칸은 참고용이에요. 원인을 사장님이 맞힐 필요는 없어요.
| 화면에서 보이는 것 | 짚이는 구간 | AI에게 이렇게 말해요 |
|---|---|---|
| 버튼을 눌러도 아무 반응이 없어요 | 신청서가 출발도 못 했어요 | "버튼을 누르면 처리 중 표시를 켜고, 실패하면 왜 실패했는지 글자로 보여줘" |
| 한참 돌다가 실패했다고 떠요 | 가는 길이나 답장이 늦어요 | "요청이 10초 안에 안 끝나면 기다림을 끊고 다시 시도 버튼을 보여줘" |
| "페이지를 찾을 수 없습니다"가 떠요 | 주소가 틀렸어요(404) | "없는 주소로 들어온 손님에게 안내 화면과 첫 화면으로 가는 버튼을 보여줘" |
| 로그인했는데 자꾸 로그인 화면으로 돌아가요 | 출입증이 풀렸어요(401) | "로그인이 만료되면 입력하던 내용을 지우지 말고, 다시 로그인한 뒤 그 화면으로 돌려보내줘" |
| 손님이 몰리는 시간에만 실패해요 | 횟수 한도에 걸렸어요(429) | "짧은 시간에 같은 요청이 몰리면 잠깐 기다렸다가 다시 보내게 해줘" |
| 저장됐다고 떴는데 목록에 없어요 | 화면만 성공한 척했어요 | "저장이 끝난 뒤에 목록을 다시 불러와서, 방금 넣은 것이 실제로 보이는지 확인하고 알려줘" |
| "알 수 없는 오류"만 떠요 | 답장을 못 읽고 있어요 | "실패했을 때 서버가 준 안내 문구를 화면에 그대로 보여주고, 기록도 남겨줘" |
고쳤는지 확인하는 방법
실패 문구가 사람 말로 바뀌었는지, 그리고 다음에 뭘 하라는 안내가 붙었는지만 보세요. "요청이 실패했습니다"에서 "카드 승인이 거절됐어요. 다른 카드로 다시 시도해 보세요"로 바뀌면 제대로 고친 거예요. 반복되는 실패는 오류 기록에 쌓이게 해 두면 나중에 원인을 찾기 쉬워요.
외주 견적과 연동 문서를 읽는 눈
이 말들은 개발자끼리 쓰는 말이지만, 견적서와 연동 문서에는 반드시 등장해요. 뜻을 모르면 그 줄을 건너뛰게 되고, 건너뛴 줄이 나중에 사장님 전화기로 돌아와요. 왼쪽 말이 보이면 가운데로 옮겨 읽고, 오른쪽을 물어보세요.
| 문서에 적힌 말 | 사장님 말로 옮기면 | 여기서 물어볼 것 |
|---|---|---|
| 요청, 리퀘스트 | 화면이 창구에 밀어 넣는 신청서 한 장 | 한 화면을 열 때 신청서가 몇 장 나가나요 |
| 응답, 리스폰스 | 창구가 돌려주는 종이 한 장 | 실패한 종이가 오면 손님은 무슨 글자를 보나요 |
| 4xx, 5xx | 종이에 찍힌 도장. 4는 보낸 쪽, 5는 받는 쪽 | 이 둘을 다르게 안내하나요 |
| 타임아웃 10초 | 10초까지만 기다리고 끊겠다는 약속 | 끊긴 뒤 화면에 무엇이 남나요 |
| 재시도, 리트라이 | 실패하면 자동으로 다시 보내기 | 결제도 자동으로 다시 보내나요. 두 번 빠지면요 |
| 에러 핸들링 | 실패했을 때 화면과 기록을 챙기는 일 | 실패 기록은 어디에 쌓이고 누가 보나요 |
성공한 경우만 적혀 있어요. 실패했을 때 손님이 볼 화면이 한 줄도 없어요.
실패를 미리 세 줄 잡아 뒀어요. 값이 비싸 보여도 문 연 뒤에는 이쪽이 더 싸요.
견적서에 이 줄들이 아예 없으면 값이 싼 게 아니라 실패를 안 만든 것이에요. 성공만 만든 화면은 문 여는 날까지 멀쩡해 보여요. 문제는 손님이 지하철에서 결제를 누르는 날 시작돼요.
싼 견적과 빠진 견적을 가르는 한 줄
"실패했을 때 손님이 보는 화면"이 견적에 적혀 있는지 보세요. 그 한 줄이 없으면 그 자리는 나중에 사장님이 전화로 때우게 돼요. 반대로 그 줄이 있으면 몇십만 원 비싼 견적이 더 싼 견적이에요.
지금은 신경 쓰지 않아도 되는 때
가게 소개 페이지, 메뉴판, 포트폴리오처럼 손님이 무언가를 보내는 자리가 없는 사이트라면 왕복이라 부를 것도 거의 없어요. 사진과 글자를 받아 오는 요청뿐이라, 실패하면 새로고침으로 끝나요. 이 문서는 덮어 두고 만들기에 집중하셔도 돼요.
하루 손님이 열 명인 가게에 자동 재시도 설계나 429 대비를 넣는 건 시간 낭비예요. 그 규모에서 필요한 건 딱 하나예요. 실패했을 때 화면에 "잠시 후 다시 시도해 주세요"와 문의 연락처가 남는 것요. 손님 열 명은 전화로 응대할 수 있어요. 설계는 손님이 그 수를 넘기고 나서 해도 늦지 않아요.
신경 쓸 때가 왔다는 신호 세 가지
돈이나 약속이 걸린 자리가 생겼을 때(결제, 예약, 신청). 손님 문의에 "실패했다"가 반복될 때. 몰리는 시간대에만 실패할 때. 이 셋 중 하나라도 보이면 그날부터는 남 얘기가 아니에요.
자주 묻는 것
- Q. "요청이 실패했습니다"만 뜨고 아무 설명이 없어요. 원래 이런 건가요?
- 아니에요. 돌아온 종이에는 보통 이유가 담겨 있어요. 화면이 그 이유를 버리고 자기 문구만 띄우고 있는 거예요. "서버가 준 안내 문구를 화면에 그대로 보여줘"라고 말하면 대부분 바로 해결돼요.
- Q. 새로고침하면 되는데, 왜 처음엔 실패한 거예요?
- 가는 길이 잠깐 끊겼거나 창구가 순간 바빴다는 뜻이에요. 한두 번은 정상 범위예요. 다만 같은 화면에서 반복되면 우연이 아니라서, 기록을 쌓아 두고 몇 시에 몰리는지 봐야 해요.
- Q. 다시 시도를 여러 번 눌렀는데 두 번 접수됐어요. 제 잘못인가요?
- 아니에요. 처리는 됐는데 답장만 못 받은 상황에서 흔히 생기는 일이에요. 같은 신청서가 두 번 처리되지 않게 막는 장치를 넣어 달라고 하세요. 결제나 예약 자리에서는 있어야 하는 장치예요.
- Q. 기다리는 시간은 몇 초로 잡는 게 맞아요?
- 자리마다 성격이 달라요. 목록을 불러오는 자리는 짧게 끊고 다시 시도하게 하는 편이 손님에게 낫고, 결제처럼 돈이 걸린 자리는 넉넉히 기다리는 편이 안전해요. 짧게 끊었다가 이미 처리된 결제를 실패로 안내하면 그게 더 큰 사고예요. 자세한 이야기는 기다림과 다시 시도에 있어요.
- Q. 자동으로 다시 보내는 게 항상 좋은 거예요?
- 찾아보기만 하는 요청은 몇 번을 다시 보내도 손해가 없어요. 그런데 결제나 예약처럼 무언가 생기는 요청은 보낼 때마다 하나씩 더 생길 수 있어요. 그래서 자동 재시도는 두 번 처리 방지 장치와 짝으로만 넣는 게 원칙이에요.
- Q. 제 인터넷 문제인지 사이트 문제인지 어떻게 구별해요?
- 다른 사이트들이 잘 열리면 내 인터넷은 멀쩡한 거예요. 그다음은 사람 수예요. 여러 손님이 같은 증상을 말하면 사이트 쪽, 나 혼자면 내 기기나 회선 쪽일 확률이 커요.
- Q. 손님에게 도장 숫자를 그대로 보여줘도 되나요?
- 숫자만 보여주면 불친절해요. 손님에게는 사람 말로 안내하고, 숫자는 기록에 남기는 게 정석이에요. 문의가 왔을 때 그 기록을 보면 개발자가 바로 짚어요.
- Q. 실패 기록은 얼마나 오래 두면 돼요?
- 문의가 들어오는 주기만큼이면 충분해요. 손님은 어제 일을 오늘 말하니까 며칠은 남아 있어야 하고, 몇 달 전 기록은 거의 안 봐요. 주문 내용이나 연락처가 섞이는 자리라면 보관 기간을 따로 정해 두는 게 안전해요.
- Q. 개발자가 "5xx라서 우리 잘못이 아니에요"라고 하면 어떻게 받아야 해요?
- 500번대가 받는 쪽 사정인 건 맞아요. 그런데 그 받는 쪽이 사장님이 돈 주고 쓰는 서버일 수도 있어요. "어느 쪽 서버에서 난 500인가요?"라고 되물으면 돼요. 남의 거래처 사정이면 그때는 진짜 그쪽 문제예요.
확인해 보세요
손님 화면에는 결제 실패라고 떴는데, 손님 카드에서는 돈이 빠졌어요. 가장 그럴듯한 설명은?
하나 더
견적서에 "4xx는 손님 안내, 5xx는 재시도"라고 적혀 있어요. 무슨 뜻일까요?
직접 해보기
실패 안내 문구부터 붙여 보세요
만든 화면에 "요청이 실패했을 때 이유와 다시 시도 버튼을 보여줘"라고 한 줄만 말해 보세요. 성공 화면만 있던 자리에 응대가 생겨요. 실패 화면이야말로 손님이 화가 난 순간에 보는 화면이에요.
스튜디오 열기더 깊이 (안 읽어도 괜찮아요)
왕복은 한 번이 아니에요 · 화면 하나를 여는 동안 신청서가 수십 장 나가요. 글씨체 받아 오기, 사진 받아 오기, 목록 받아 오기가 각각 한 장이에요. 그래서 "사이트가 느려요"는 사실 왕복이 너무 많다는 뜻일 때가 많아요. 한 장 한 장을 줄이거나 합쳐서 보내는 이야기는 성능에서 다뤄요.
도장이 늘 정직한 건 아니에요 · 잘 처리된 척 200을 찍고, 종이 내용 안에 실패를 적어 보내는 창구도 있어요. 개발자가 "200인데 실패예요"라고 하면 이 경우예요. 규격이 그런 창구도 있고 만든 쪽이 게을러서 그런 경우도 있어요. 어느 쪽이든 숫자만 믿지 말고 종이 내용까지 읽어야 한다는 뜻이에요.
같은 신청서를 두 번 보내도 한 번만 처리되게 · 신청서마다 고유 번호를 달아 두면, 창구가 "이미 받은 번호"를 알아보고 두 번 처리하지 않아요. 답장이 끊겨서 손님이 다시 시도를 눌러도 돈이 두 번 빠지지 않는 장치예요. 견적서나 연동 문서에 이 줄이 있으면 실무를 아는 팀이에요. 결제 쪽 이야기는 결제 연동에 이어져요.
이것만 기억하세요
- ·요청은 창구에 밀어 넣는 신청서, 응답은 돌아오는 종이예요
- ·실패는 네 구간(내 화면, 가는 길, 창구, 돌아온 답장) 중 어디서 막혔는지로 갈려요
- ·세 자리 도장에서 400번대는 보낸 쪽, 500번대는 받는 쪽 사정이에요
- ·원인을 맞히지 말고 몇 시에, 어느 화면에서, 얼마나 기다렸는지를 적어 넘기세요
- ·손님이 무언가 보내는 자리가 없다면 아직 신경 쓸 일이 아니에요