5강. 에러 설계가 시스템 신뢰도를 결정한다

🤔 Question

👉 이런 경험 있으신가요?

"API가 실패했는데 왜 실패했는지 모르겠어요."
"에러 메시지가 매번 달라서 처리하기 힘들어요."
"재시도해도 되는 에러인지 알 수가 없어요."

MSA 환경에서
이런 에러는 곧 장애로 이어집니다.

그 이유는 하나입니다.
👉 에러도 계약인데, 그 계약이 설계되지 않았기 때문입니다.

 

🎯 상태코드만 맞추면 끝일까?

많은 개발자가 에러 설계를
HTTP 상태코드로 끝낸다고 생각합니다.

✔ 400 Bad Request
✔ 401 Unauthorized
✔ 404 Not Found
✔ 500 Internal Server Error

물론 중요합니다.
하지만 이것만으로는 부족합니다.

👉 소비자는 "왜 실패했는지"와 "어떻게 대응해야 하는지"를 알아야 합니다.

 

🎯 실무에서 자주 만나는 나쁜 에러

{
  "message": "Error occurred"
}

이 에러를 받은 소비자는
아무 것도 할 수 없습니다.

👉 재시도를 해야 할까?
👉 입력값을 바꿔야 할까?
👉 관리자에게 문의해야 할까?

정보가 없으면 시스템은 멈춥니다.

 

🎯 좋은 에러는 복구 가능하게 만든다

{
  "errorCode": "ORDER_ALREADY_CANCELLED",
  "message": "이미 취소된 주문입니다.",
  "retryable": false
}

이제 소비자는 알 수 있습니다.

✔ 왜 실패했는지
✔ 다시 시도할 필요가 없는지
✔ 사용자에게 어떤 메시지를 보여줄지

👉 좋은 에러 설계는 시스템을 복구 가능하게 만듭니다.

 

🎯 도메인 에러와 시스템 에러를 구분하라

에러에는 두 종류가 있습니다.

✔ 도메인 에러 → 비즈니스 규칙 위반
✔ 시스템 에러 → 네트워크, DB, 타임아웃 등

예시를 보겠습니다.

주문 금액이 부족함 → 도메인 에러
결제 서버 다운 → 시스템 에러

👉 이 둘을 구분하지 않으면 재시도 로직이 망가집니다.

 

🎯 에러 포맷도 계약이다

성공 응답만 계약이 아닙니다.
에러 응답도 계약입니다.

👉 모든 API가 동일한 에러 포맷을 사용해야
소비자는 공통 처리 로직을 만들 수 있습니다.

이때 중요한 것은
"개발자 편한 에러"가 아니라
소비자가 다룰 수 있는 에러입니다.

 

🎯 신뢰는 에러에서 결정된다

정상 흐름은 누구나 설계합니다.
하지만 장애 상황에서
API가 어떻게 실패하는지가 진짜 실력입니다.

👉 예측 가능한 실패는 신뢰를 만듭니다.
👉 예측 불가능한 실패는 시스템을 무너뜨립니다.

 

☔ 정리

👉 에러도 API 계약의 일부입니다.
👉 좋은 에러 설계는 복구 가능한 시스템을 만듭니다.
👉 시스템 신뢰도는 정상 응답이 아니라
실패 응답에서 결정됩니다.

 

 

If I was of any help to you, please buy me coffee 😿😢😥

If you have any questions, please leave them in the comments

Buy me a coffee

▶ Youtube Sub

🧭 References

[1] reference : https://doctorson0309.tistory.com/

[2] Ads : https://apps.apple.com/us/app/beluga-classic-film-filters/id6744041061