[Develop] 공통 응답 형식과 에러코드 관련 논의

[Seol-JY]

Client 측에서 응답 Json을 일관성 있게 처리할 수 있도록 응답 성패에 관계없이 항상 같은 형식을 유지할 수 있게 공통
응답 형식을 설계했습니다.

현재 결정된 공통 응답 형식은 다음과 같습니다.
AS-IS

{
	"status":  "응답 상태는 String으로 표시(success, fail, error 중 하나 리턴)"
	"message": "예외일 경우 에러메시지 표시, 예외가 아닐 경우 null로 처리"
	"data": {"응답 결과는 json(success일 경우 응답 데이터, error일 경우엔 null) 반환"}
}

http 상태 코드는 200으로 통일

다만, 위 방식에 대해 몇 가지 문제가 발생할 것이라 예상됩니다.

1. 상태코드의 역할이 모호해짐.
2. status 필드를 통해 요청에 대한 응답 상태(성공 또는 실패)는 알 수 있지만, 실패 사유에 대해서는 message 필드를 확인해야 함.
3. 2번으로 인해 Client에서 상세 에러 핸들링을 위해 message 필드를 직접 비교하는 작업이 수반될 것으로 예상되고, 이는 적절치 못함.

따라서 다음과 같이 응답 형식을 변경하고, status가 아닌 자체 상태 코드를 반환하는 것을 제안합니다.
TO-BE

{
	"code":  "성공 시 200, 실패 시 자체 에러 코드 반환(자체 에러 코드를 바탕으로 에러 핸들링)"
	"message": "예외일 경우 에러메시지 표시, 예외가 아닐 경우 null로 처리(단순히 응답에 대한 설명 제공)"
	"content": {"응답 결과는 json(success일 경우 응답 데이터, error일 경우엔 null) 반환"}
}

http 상태코드는 표준을 따른다.

이렇게 되면, Client에서는 공통 응답 내부 code 필드를 통해 응답 성패여부, 상세 실패 원인을 파악하고 이를 통해 에러를
핸들링 할 수 있게 됩니다. 다만, 에러 코드 명세와 에러 코드 규격화에 대한 논의가 함께 이루어져야 합니다.

제안한 공통 응답형식이 적절한지, 에러 코드를 어떤 방법으로 규격화해 사용할지에 대해 함께 의논해 보고자 합니다.

아래는 참고한 실제 Naver Chzzk의 Api 응답 형식입니다.

[Junad-Park]

확실히 처음 방식은 상태코드의 역할이 애매했는데 자체 에러 코드를 사용하는게 더 명확해지는 것 같습니다!
자체 에러 코드 규칙만 잘 설정한다면 좋은 방식인 것 같습니다!

[Seol-JY]

회의와 피드백을 통해 공통 응답 형식을 재설계 했습니다.

응답 성공시(20000 코드 고정)
성공 응답

{
	"code": 20000,
	"content": {},
	"message": null,
} 

응답 실패시

• 프론트에서 해당 코드를 통해 에러 처리를 수행

{
	"code": 4----,
	"content": null,
	"message": "사유",
} 

• 프론트에서 적절한 Validation을 해서 응답을 보내도록 해야함

{
	"code": 30001,
	"content": null,
	"message": "validation 실패 사유",
} 

서버 에러

• 백엔드 코드 결함, 문의할 것

{
	"code": 50001,
	"content": null,
	"message": "서버 오류입니다.",

도메인	에러코드	비고
Validation	30001	message에 상세 실패 사유
auth	401xx	40101~
user	402xx
teamspace	403xx
schedule	404xx
chat	405xx
file	406xx
feed/common	471xx
feed/normal	472xx
feed/vote	473xx
feed/scheduling	474xx
feed/collect	475xx	47501~
기타	499xx

[ledraco]

Client에서 code 필드를 통해 상세 실패 원인을 파악하고 에러 핸들링 할 수 있다는 점에서 좋은 방식이라 생각합니다.
에러 코드 명세에 대한 비용이 발생하겠지만, 명세 이후 보다 효율적인 개발이 가능할 것 같습니다!

[0Jaemin0]

자체 에러 코드를 사용함으로써 프론트 측에서 응답 실패 시 자체 에러 코드를 통해 구체적인 실패 원인을 파악하고 에러 처리를 할 수 있는 점이 장점인 것 같습니다.