423 Locked: 잠금을 추적해 해제하기

문제

요청을 보냅니다 — 저장, PUT, MOVE, API 쓰기 — 그런데 423 Locked가 돌아옵니다. 당신이 보낸 것에는 잘못이 없습니다. 리소스 자체가 접근 금지 상태입니다: 무언가 그것에 잠금을 걸었고, 서버는 그 잠금이 사라지기 전까지 두 번째 쓰기 주체가 손대는 걸 거부합니다. 이건 상태 충돌도 권한 문제도 아닙니다. 예약입니다. 누군가, 또는 어떤 프로세스가 리소스를 쥐고 있고, 서버는 그 쥔 쪽이 덮어쓰이지 않도록 보호하는 중입니다. 당신이 할 일은 누가 잠금을 쥐고 있는지 — 그리고 그게 당신인지 — 를 알아내는 것입니다.

증상

• 응답 상태가 423 Locked입니다. WebDAV에서는 본문이 <DAV:lock-token-submitted>나 <DAV:no-conflicting-lock> 같은 사전조건 요소를 담은 XML입니다.
• SharePoint·OneDrive·Office에서는 사람이 보는 버전이 “이 파일은 편집을 위해 잠겨 있습니다” 또는 “<누군가>가 공유 사용을 위해 잠갔습니다”로 나옵니다.
• 잠금이 풀리면 같은 쓰기가 성공합니다 — 문서를 닫거나 세션을 끝내거나 타임아웃을 기다리면 오류가 저절로 사라집니다.
• 브라우저로 URL을 치면 423을 보는 일이 없습니다. 브라우저는 이를 일반 400으로 취급합니다. 진짜 423을 보고 있다면 당신은 WebDAV 클라이언트, API, 또는 서버 로그를 다루는 중입니다.

이 오류의 실제 의미

423은 WebDAV 명세인 RFC 4918 §11.3에서 정의됐습니다: “메서드의 소스 또는 대상 리소스가 잠겨 있다.” WebDAV는 편집 전에 리소스를 LOCK할 수 있게 해, HTTP로 같은 파일을 편집하는 두 작성자가 서로를 조용히 덮어쓰지 못하게 했습니다 — “손실된 갱신 문제(lost update problem)”. 잠금을 획득하면 서버가 *잠금 토큰(lock token)*을 건넵니다. 잠금이 걸린 동안 변경하려면 그 토큰을 If 요청 헤더에 되돌려 제시해야 합니다. 토큰이 없거나 틀리면 쓰기는 423과 DAV:lock-token-submitted 사전조건으로 거부됩니다. 이미 잠긴 멤버를 담은 컬렉션에 대한 충돌하는 depth-infinity LOCK도 같은 방식으로, DAV:no-conflicting-lock과 함께 실패합니다.

평범한 웹 서버는 스스로 리소스를 잠그지 않으므로, 오늘날 대부분의 423은 두 곳에서 옵니다. 첫째는 이것이 설계된 WebDAV 세계 — SharePoint·OneDrive·Nextcloud, 그리고 Office-over-WebDAV 구성 — 로, 데스크톱 앱에 열린 파일은 앱이 닫힐 때까지 편집에 대해 잠깁니다. 둘째는 현대 API가 423을 범용 “이 리소스는 예약됨” 신호로 빌려 쓴 경우입니다: 워크플로가 체크아웃한 레코드, 편집 세션이 쥔 문서, 실행 중 자기 행을 잠근 작업, 작업 도중 동결된 계정. 둘 다 의미는 같습니다: 리소스는 임자가 있고, 해법은 예약을 해제하는 것이지 더 세게 재시도하는 게 아닙니다.

주요 원인 3가지

1. 파일이 데스크톱 앱에 열려 있다 (SharePoint / Office / OneDrive) - 순수 WebDAV 밖에서 압도적으로 흔한 원인. 누군가 Word·Excel이나 동기화 클라이언트에 문서를 열어 두어 편집 잠금이 유지됩니다. 그 앱이 닫히고 — 닫힌 뒤 유예 시간이 지나기 전까지 — 다른 모든 쓰기는 423을 받습니다. 앱이 크래시했다면 잠금은 고아가 되어 설정한 사람보다 오래 남습니다.
2. 쥐고 있어야 할 잠금 토큰을 제출하지 않았다 - 당신(또는 당신 클라이언트)이 리소스를 LOCK했지만 이어진 쓰기가 If 헤더에서 토큰을 빠뜨렸거나 오래된 것을 보냈습니다. 서버는 당신의 쓰기를 침입자의 것과 구분할 수 없어 DAV:lock-token-submitted로 거부합니다. 이건 클라이언트 측 버그입니다: 잠금을 획득한 다음, 그 토큰을 이후 모든 요청에 꿰어 넣으세요.
3. API가 의도적으로 거는 애플리케이션 계층 잠금 - 엔드포인트가 워크플로 도중 리소스를 일부러 잠급니다 — 편집을 위해 체크아웃된 문서, 결제 중 잡아 둔 예약, 실행 중 자기 레코드를 예약한 작업, 일시 동결된 계정. 이 423은 설계대로 작동하는 것 — 잠금을 취한 작업을 끝내거나 취소하거나, 그 타임아웃을 기다려 해소합니다.

DechoNet으로 진단하기

• HTTP 진단은 엔드포인트가 실제로 423을 반환하는지 확인하고 응답 헤더와 본문을 잡아냅니다 — 잘 만든 WebDAV·API 서버라면 잠금 소유자, 사전조건 요소, 또는 Retry-After 힌트가 담기는 곳이 바로 본문입니다. 그 본문이 “기다려라”와 “토큰을 제출하라”를 가르는 갈림길입니다.
• 또한 423이 프록시나 게이트웨이가 다른 무언가를 재작성한 게 아니라 오리진에서 나왔는지 확인해, 실제로 잠금을 쥔 계층을 쫓게 합니다. 실패하는 엔드포인트가 아예 이름 해석이 안 되는 호스트라면, DNS 진단이 애플리케이션 오류로 위장한 단순 도달 불가 문제를 배제해 줍니다.

해결 체크리스트

• 상태가 아니라 응답 본문을 읽으세요. WebDAV는 문제를 이름 붙입니다: lock-token-submitted는 당신이 토큰을 제시해야 한다는 뜻, no-conflicting-lock은 기존 잠금이 앞을 막는다는 뜻입니다. API는 흔히 리소스를 쥔 소유자나 작업을 명시합니다.
• 당신의 잠금이라면 토큰을 제출하세요. 활성 잠금 토큰을 쓰기의 If 헤더에 넣거나, 토큰이 만료됐다면 다시 LOCK하세요. 클라이언트가 잠금을 획득하고 해제하지 않았다면 UNLOCK하세요.
• 데스크톱 앱이 쥐고 있다면, 그 파일을 열었던 모든 기기에서 앱을 완전히 닫고 유예 시간을 기다리세요. SharePoint·OneDrive에서는 파일의 “잠근 사람” 정보를 확인하세요 — 아무도 안 보는 기기의 동기화 클라이언트가 전형적 범인입니다.
• 잠금이 고아 상태 — 쥔 쪽은 사라졌는데 잠금은 살아 있음 — 라면 무작정 재시도하지 마세요. 타임아웃을 기다리거나 관리자/소유자가 강제 해제하게 하세요(SharePoint의 “체크인”/체크아웃 취소, 토큰을 쓴 UNLOCK, 또는 API의 관리자 잠금 해제).
• 423을 이웃과 혼동하지 않았는지 확인하세요: 잠금은 없는데 상태가 충돌하면 409, If-Match 실패는 412, 필수인데 누락된 사전조건은 428, 다른 실패로부터의 연쇄는 424입니다. 각각 해법이 다릅니다.

언제 에스컬레이션할까

• 리소스가 식별 가능한 소유자도 없고 타임아웃도 보이지 않은 채 잠겨 있다면, 시스템이 스스로 회수하지 않는 고아 잠금입니다. 이건 호출자가 재시도로 고칠 수 없는 운영자 작업 — 강제 해제나 잠금 정리 — 입니다.
• 동시성 상황에서 423이 나타난다면(여러 쓰기 주체가 같은 리소스를 동시에 침) 잠금은 제 일을 하는 중이지만 당신의 워크플로가 뜨거운 리소스에서 직렬화되고 있는 것입니다. 이건 개별 요청의 버그가 아니라 설계 문제 — 잠금 유지 시간 단축, 잠금 범위 축소, 쓰기 주체 큐잉 — 입니다.
• 423을 반환하는 API를 당신이 소유한다면, 응답 본문에 누가 잠금을 쥐었고 언제 만료되는지 담으세요. 소유자도 Retry-After도 없는 맨 423은 셀프서비스로 기다리면 될 일을 지원 티켓으로 만듭니다.