--- title: Runbook — DEPENDENCY_4XX_CLIENT (업스트림 클라이언트 오류) category: PERMANENT_DEPENDENCY error_codes: [DEPENDENCY_4XX_CLIENT] severity: P2 owner: oncall last_updated: 2026-11-13 status: 초안 --- # Runbook: DEPENDENCY_4XX_CLIENT (`runbook://dependency/4xx-client`) ## 증상 - HTTP 502, `error.code=DEPENDENCY_4XX_CLIENT`. - 업스트림이 401·403·400을 돌려줬다. 자격 증명, scope, 요청 형식 문제다. - 이 코드는 서비스 코드가 `DependencyFailureException`을 던질 때만 나온다. httpclient 예외는 코드를 싣지 않아 500 `INTERNAL_ERROR`다(`dependency-unavailable.md`). - ERROR 줄 `dependency failure classified as DEPENDENCY_4XX_CLIENT (category=PERMANENT_DEPENDENCY, retryable=false, dependency=<이름>)`(`ServerFailureLog`, 원인 사슬 포함). ## 진단 - 업스트림 응답 본문은 로그에 남지 않는다(본문은 비밀·개인 정보를 실을 수 있어 남기지 않는다). 그 줄의 `dependency=`와, httpclient capability를 켠 서비스는 `http.client.requests`의 tag `clientName`·`status`로 어느 업스트림이 어떤 4xx를 돌려줬는지 본다. 본문은 업스트림 쪽 로그나 재현으로 본다. - API 자격 증명과 scope가 유효한지 확인한다. ## 조치 - 자격 증명이 만료됐으면 교체한다. - API 계약이 바뀌었으면 요청 형식을 고친다. ## 에스컬레이션 - 계약 변경이 의심되면 업스트림 API 소유자에게 넘긴다. --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.