[웹 개발] API 에러 응답 설계, 어디까지 정해야 할까?

https://claremont.tistory.com/entry/%EC%9B%B9-%EA%B0%9C%EB%B0%9C-API-%EB%AA%85%EC%84%B8%EC%84%9C-%EC%9E%91%EC%84%B1-tip

[웹 개발] API 명세서 작성 tip

 

API 서버를 개발하다 보면 반드시 마주하게 되는 질문이 있다
“에러 응답은 어떻게 설계하지?”

많은 개발자들이 HTTP 상태 코드만 잘 쓰면 되는 거 아닌가? 하고 생각할 수도 있다. 하지만 실제 운영 단계에 들어가면 단순한 HTTP 코드만으로는 부족한 경우가 많다. 프론트엔드와 백엔드 사이의 명확한 소통, 로그 추적, 사용자에게 보여줄 메시지 처리 등을 고려하면 "커스텀 에러 코드 체계"가 필요한 이유를 자연스럽게 알게 된다.

 

이번 글에서는 실제 프로젝트에서 쓰이는 에러 응답 설계 가이드를 공유하려 한다.

 

1. HTTP Status Code 만으로 충분할까?

모두 다 알다싶이, HTTP에는 이미 정해진 상태 코드 체계가 존재한다

• 2xx: 성공 (예: 200 OK, 201 Created)
• 4xx: 클라이언트 오류 (예: 400 Bad Request, 401 Unauthorized)
• 5xx: 서버 오류 (예: 500 Internal Server Error)

이 상태 코드들은 요청 자체가 잘 도착했는지, 혹은 서버에 문제가 있었는지를 판단하는 데에는 충분하다. 하지만 실제 서비스 상황에서는 그보다 더 세밀한 이유가 필요하다.

예를 들어, 로그인 API에서 ID 또는 비밀번호가 틀린 경우, HTTP 기준으로는 200 OK를 주는 것이 맞다. 왜냐하면 클라이언트가 요청을 잘 보냈고, 서버도 그 요청을 정상적으로 처리했기 때문이다. 하지만 결과적으로는 로그인에 실패한 것이므로 클라이언트는 “왜 실패했는지”를 더 알아야 한다.

 

2. 그래서 등장하는 커스텀 에러 코드 체계

많은 기업이나 개발팀은 위 문제를 해결하기 위해 자체적으로 API 응답 포맷과 에러 코드 체계를 정의한다. 참고로 내가 참여한 프로젝트에서는 대강 다음과 같은 형태로 응답을 구성했었다.

{
  "result": 1,
  "code": 20006,
  "message": "ID 또는 PW가 틀립니다.",
  "body": null
}

 

이 구조는 다음과 같은 장점을 갖는다

1. API 응답 포맷이 일관성 있게 유지된다 (유지보수성 up)

2. 프론트엔드는 code 값만 보고 어떤 에러인지 분기 처리를 할 수 있다!

3. 서버 로그에서 code로 필터링하면 문제 파악이 쉬워진다

4. message를 활용해 사용자에게 친절하게 안내할 수 있다

 

 

그렇다면 저기에 사용되는 에러 코드는 어떤 관습이 있을까?

 

3. 커스텀 에러 코드, 어떤 규칙으로 만들까?

에러 코드를 정할 때 가장 흔히 쓰이는 방식 중 하나는 앞자리 숫자로 에러의 유형을 나누는 것이다. 대표적은 Best-Pratice는 아래와 같다

 

예를 들어, 로그인 실패 시 20006처럼 20000번대 코드 중 하나를 할당하고, 필수 파라미터가 누락된 경우에는 40011 같은 코드를 부여하는 방식이다.

이 규칙은 어떤 공식 표준은 아니다. 하지만 실무에서 많이 쓰이는 컨벤션이며, 국내외 여러 기업에서 이와 유사한 방식으로 API 에러 코드를 관리한다. 팀 규모가 커지거나 프론트-백 간 협업이 많아질수록 이런 구조는 점점 더 빛을 발한다✨

 

4. HTTP 상태 코드와 커스텀 에러 코드는 함께 써야 한다

 

중요한 점은, HTTP 상태 코드와 커스텀 에러 코드 중 하나만 쓰는 것이 아니라, 둘을 함께 써야 한다는 것이다.

• HTTP 상태 코드는 요청/응답의 기술적 상태를 나타낸다
• 커스텀 에러 코드는 비즈니스 로직의 상태를 나타낸다

 

5. 그런데.. 꼭 이 방식이어야 할까?

결론적으로, 내가 사용한 result / code / message 구조는 공식 표준은 아니다. 하지만 일관성, 명확성, 협업 편의성을 갖춘 매우 실용적인 방식이고, 실무에서도 널리 사용된다.

 

다만, 반드시 이 숫자 규칙을 따라야 한다는 법은 없다.
어떤 팀은 E1001, E4002처럼 문자열 기반의 코드 체계를 쓰기도 하고,
어떤 팀은 status: "DB_ERROR" 같은 문자열 Enum 방식으로 구성하기도 한다.

중요한 건 팀 내에서 일관되게 정의하고, 프론트엔드와 명확히 소통할 수 있도록 문서화하는 것이다!

---

 

마치며.....

 

API 응답 설계는 단순히 데이터를 주고받는 기술적인 문제가 아니다. 시스템 운영의 안정성과 사용자 경험, 개발자 간의 커뮤니케이션까지 모두 영향을 미친다. 따라서 작은 프로젝트라도 처음부터 응답 포맷과 에러 코드 체계를 고민해 두는 것이 중요하다. 나 역시 이번 프로젝트에서 이런 체계를 도입하면서 문제 추적 속도도 빨라지고, 협업 난이도도 눈에 띄게 줄어들었다. 혹시 지금 API 설계를 고민 중이라면, 위의 구조를 참고해보길 추천한다. 팀 상황에 맞게 변형하는 것도 얼마든지 가능하다 :)