--- title: Runbook — DEPENDENCY_5XX_SERVER (업스트림 서버 오류) category: TRANSIENT_DEPENDENCY error_codes: [DEPENDENCY_5XX_SERVER] severity: P1 owner: oncall last_updated: 2026-11-13 status: 초안 --- # Runbook: DEPENDENCY_5XX_SERVER (`runbook://dependency/5xx-server`) ## 증상 - HTTP 502, `error.code=DEPENDENCY_5XX_SERVER`. - 업스트림이 5xx를 돌려줬다. 서버 쪽 일시 장애다. - 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`). - ERROR 줄 `dependency failure classified as DEPENDENCY_5XX_SERVER (category=TRANSIENT_DEPENDENCY, retryable=true, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함). ## 진단 - 그 줄의 `dependency=`가 서비스가 붙인 업스트림 이름이다. httpclient capability를 켠 서비스는 `http.client.requests`의 tag `clientName`·`outcome`으로도 본다. - 업스트림 서비스의 상태 페이지를 본다. ## 조치 - 클라이언트는 다시 시도한다(retryable=true). - 업스트림 회복을 지켜본다. ## 에스컬레이션 - 중요한 업스트림이 5xx 상태로 계속 머물면 P1. --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.