API 문서 오류 코드, 왜 숫자보다 뜻부터 볼까요
API 문서 오류 코드 이해가 필요한 순간은 보통 회의 중에 갑자기 옵니다. 화면에는 400, 401, 403, 404, 500 같은 숫자가 뜨고, 개발자는 “응답 코드가 이렇게 왔다”고 말합니다.
처음 들으면 살짝 멀게 느껴져요. 그런데 이 숫자는 암호라기보다 “어디부터 확인할지” 알려주는 표지판에 가깝습니다.
API 문서 오류 코드 이해에서 제일 먼저 볼 건 숫자 하나가 아니라 앞자리입니다. 4로 시작하면 요청한 쪽에서 확인할 일이 많고, 5로 시작하면 서버나 연동 시스템 쪽을 의심해볼 수 있어요.
PM이나 기획자가 코드를 직접 고칠 필요는 없습니다. 대신 어떤 질문을 해야 하는지 알면 회의가 덜 빙빙 돕니다. 이거 은근 중요합니다.
숫자를 보는 기준이 생기면 말투도 달라집니다. “오류가 났어요”에서 “인증 쪽부터 보면 될 것 같아요”로 바뀌니까요.
기능정의서 작성방법을 정리할 때 기능 이름과 예외 상황을 나눠 적듯이, 오류 코드도 요청 문제인지, 인증 문제인지, 권한 문제인지, 서버 문제인지 먼저 나눠보면 훨씬 덜 복잡합니다.
400번대가 뜨면 먼저 요청을 봅니다
API 문서 오류 코드 이해에서 400번대는 “보낸 요청이 괜찮은지 먼저 보자”는 신호로 잡으면 편합니다. 물론 실제 원인은 더 깊을 수 있지만, 출발점은 요청값입니다.
400은 필수값이 빠졌거나 형식이 맞지 않을 때 자주 봅니다. 날짜 형식이 다르거나, 문서에는 `userId`라고 되어 있는데 실제 요청에는 다른 이름으로 보냈을 수도 있어요.
401은 인증 쪽입니다. 토큰이 없거나 만료됐거나, 인증 헤더가 빠졌을 때 나올 수 있습니다.
403은 권한입니다. 로그인은 되었는데 해당 기능을 볼 수 없는 계정일 때 의심하면 됩니다.
| 코드 | 쉽게 보면 | 회의에서 물어볼 말 |
|---|---|---|
| 400 | 요청값 문제 | 필수값이나 형식이 맞나요 |
| 401 | 인증 문제 | 토큰이 빠졌거나 만료됐나요 |
| 403 | 권한 문제 | 이 계정에 접근 권한이 있나요 |
| 404 | 주소·대상 문제 | URL이나 데이터가 맞나요 |
API 문서 오류 코드 이해가 처음이라면 이 표 정도만 손에 익혀도 충분합니다. 모든 코드를 외우는 것보다 자주 만나는 숫자를 상황에 붙이는 게 더 빠릅니다.
401과 403은 어디서 갈릴까요
처음에는 401과 403이 비슷해 보여요. 둘 다 막히니까요. 그래도 실제 확인 방향은 꽤 다릅니다.
401은 “누구인지 확인이 안 됐다”에 가깝습니다. 403은 “누구인지는 알겠는데, 이 기능은 못 들어간다”에 가깝고요.
회의에서는 이렇게 말하면 됩니다. “토큰이 없는 건지, 토큰은 있는데 권한이 부족한 건지 나눠서 볼까요.” 이 문장 하나면 개발자도 확인 방향을 잡기 쉽습니다.
API 문서 오류 코드 이해는 개발자 흉내를 내자는 얘기가 아닙니다. 서로 같은 문제를 두고 다른 말을 하지 않게 만드는 작은 번역표입니다.
권한이 섞인 기능이라면 요구사항정의서와 기능정의서 차이도 같이 보면 좋습니다. 요구사항에는 “누가 무엇을 해야 하는지”가 들어가고, 기능정의서에는 그 권한 차이가 더 구체적으로 내려오기 때문입니다.
404는 여기서 많이 헷갈립니다
API 문서 오류 코드 이해에서 404를 웹페이지 없음으로만 기억하면 반쪽짜리입니다. API에서는 주소가 맞아 보여도 특정 데이터가 없을 때 404가 나올 수 있습니다.
예를 들어 주문 상세를 부르는데 주문 번호가 틀렸거나, 테스트 서버에는 데이터가 없거나, 주소 버전이 바뀐 경우가 있습니다. 겉으로는 다 “찾을 수 없음”처럼 보여요.
이때는 URL, HTTP 메서드, 파라미터, 테스트 데이터 존재 여부를 같이 봐야 합니다. GET으로 조회해야 하는데 POST로 보냈거나, v1 주소와 v2 주소가 섞였을 수도 있어요.
API 문서 오류 코드 이해를 QA에 붙이면 더 실용적입니다. 정상 케이스만 보지 말고 없는 데이터, 만료된 데이터, 권한 없는 데이터도 같이 넣으면 좋습니다. 테스트 케이스 작성법을 볼 때도 이 관점이 꽤 도움이 돼요.
500번대는 무엇을 넘겨야 빠를까요
500번대가 나오면 사용자가 입력을 잘못했다기보다 서버나 중간 시스템에서 막힌 상황일 수 있어요. 여기서 PM이 할 일은 원인을 단정하는 게 아니라 재현 정보를 잘 넘기는 일입니다.
발생 시간, 화면 이름, 요청한 계정, 입력값, 반복 여부를 적어두면 좋습니다. “안 돼요”보다 “오후 2시 10분, 관리자 계정, 주문 상세 조회에서 500이 반복됩니다”가 훨씬 빠릅니다.
API 문서 오류 코드 이해가 되면 장애 공유도 짧아집니다. 숫자를 붙여서 말하면 문제의 냄새가 조금 더 선명해지거든요.
잠깐 정리하면 이렇습니다.
- 400번대는 요청, 인증, 권한, 주소를 먼저 봅니다.
- 500번대는 서버나 연동 시스템 상태를 의심합니다.
- 401과 403은 인증과 권한을 나눠서 봅니다.
- 오류를 넘길 때는 발생 시간과 화면 이름을 같이 적습니다.
이 정도만 챙겨도 회의에서 말이 훨씬 짧아집니다.
자주 나오는 질문
API 문서 오류 코드 이해는 개발자만 알아도 되나요
아닙니다. 코드를 직접 고치지 않아도 PM, 기획자, 운영 담당자가 큰 뜻을 알면 협업이 훨씬 편해집니다.
특히 장애 공유나 QA 중에는 오류 코드가 짧은 공통 언어가 됩니다. 400번대인지 500번대인지 정도만 알아도 누구에게 먼저 확인을 요청해야 할지 감이 잡힙니다.
이 정도만 알아도 회의에서 “일단 개발자에게 넘기자”가 아니라 “요청값부터 볼지, 서버 로그부터 볼지”를 나눌 수 있습니다.
API 문서 오류 코드 이해에서 400과 500만 알아도 충분한가요
처음에는 충분합니다. 400번대는 요청한 쪽, 500번대는 서버 쪽이라고 크게 나누는 것부터 시작하면 됩니다.
그다음에 401, 403, 404를 따로 보면 좋아요. 인증, 권한, 주소 문제를 나눌 수 있으면 같은 오류도 덜 뭉뚱그려 보입니다.
처음부터 모든 상태 코드를 외우는 것보다 자주 보는 숫자를 업무 상황에 붙여보는 쪽이 훨씬 오래 갑니다.
API 문서 오류 코드 이해가 안 될 때 어디부터 보면 좋나요
전체 상태 코드 목록을 처음부터 외우려 하지 않아도 됩니다. 자주 만나는 400, 401, 403, 404, 500만 먼저 보세요.
그다음에는 API 문서의 오류 응답 예시와 요청 파라미터를 같이 보면 됩니다. 숫자만 보면 딱딱하지만, 예시와 같이 보면 “아 이래서 막혔구나”가 조금씩 보입니다.
특히 에러 메시지에 어떤 필드가 빠졌는지, 어떤 권한이 부족한지 적혀 있으면 그 문장을 그대로 메모해두세요.
회의 전에 확인할 것은 이 정도입니다
API 문서 오류 코드 이해는 완벽한 암기가 목표가 아닙니다. 숫자를 보고 요청, 인증, 권한, 주소, 서버 문제 중 어디를 먼저 볼지 고르는 정도면 충분합니다.
지금 보고 있는 오류 코드가 있다면 숫자만 따로 보지 말고 화면 이름, 계정 권한, 테스트 데이터, 발생 시간을 같이 적어두세요. 그 작은 메모가 다음 QA나 장애 공유에서 시간을 꽤 줄여줍니다.
회의 전에는 이 네 가지를 먼저 적어두면 충분합니다.
