426 Upgrade Required 오류 해결

Problem

요청이 예상한 응답 대신 426 Upgrade Required를 반환합니다.

Symptoms

• HTTP Check의 최종 상태 코드가 426으로 표시됩니다.
• 같은 엔드포인트가 브라우저에서는 되는데 curl, 스크립트, SDK에서는 실패합니다.
• 응답에 TLS/1.2, h2, websocket 같은 프로토콜을 지정한 Upgrade 헤더가 들어 있습니다.

이 오류의 실제 의미

426은 서버가 이렇게 말하는 것입니다. 이 요청은 처리할 수 있지만, 당신이 쓰는 프로토콜로는 안 된다. 서버는 현재 프로토콜을 거부하고 더 나은 것을 가리킵니다. 이 상태 코드는 RFC 2817(2000)에서 태어났는데, 서버가 평문 HTTP/1.1 안에서 TLS 업그레이드를 요구할 수 있도록 426을 정의했습니다. 이후 RFC 9110이 이를 HTTP 핵심 의미론에 통합했습니다.

핵심은 함께 오는 요구사항입니다. 426 응답은 서버가 받아들일 프로토콜 토큰을 나열한 Upgrade 헤더 필드를 반드시(MUST) 포함해야 합니다. 보통 Connection: upgrade가 함께 옵니다. 그래서 올바른 426은 결코 막다른 길이 아니라 답을 건네줍니다. Upgrade 값을 읽고 그 프로토콜로 요청을 다시 보내면, 정상 결과는 101 Switching Protocols입니다.

이것이 426을 이웃 코드와 구분합니다. 505 HTTP Version Not Supported는 서버가 그 HTTP 버전을 아예 안 한다는 뜻으로 업그레이드를 제시하지 않습니다. 400 Bad Request는 요청 형식 오류입니다. 403 Forbidden은 요청은 정상이나 권한이 없다는 뜻입니다. 426은 요청은 맞고 회선이 틀렸다 — 여기 내가 원하는 회선이 있다, 입니다.

Top 3 Causes

1. HTTPS 전용 엔드포인트를 평문 HTTP로 호출 - API가 TLS를 요구하므로 평문 요청을 426과 Upgrade: TLS/1.2(또는 그 이상) 헤더로 거부합니다. 원조 RFC 2817 사용 사례이자 현장에서 가장 흔한 원인입니다.
2. 엔드포인트가 HTTP/2 또는 WebSocket 핸드셰이크를 요구하는데 HTTP/1.1로 보냄 - 일부 gRPC 게이트웨이, 스트리밍 API, 실시간 엔드포인트는 h2나 WebSocket Upgrade만 받습니다. 평문 HTTP/1.1 GET은 갈 곳이 없어 서버가 원하는 프로토콜과 함께 426을 반환합니다.
3. 클라이언트 라이브러리가 옛 프로토콜에 고정됨 - 평문이나 HTTP/1.1 전용으로 설정된 SDK·HTTP 클라이언트는 서버 요구를 하나도 충족하지 못합니다. 애플리케이션 코드는 맞아 보이는데 전송 계층이 틀린 것입니다.

Diagnose with DechoNet

• HTTP Check로 최종 코드가 426인지 확인하고 Upgrade 헤더를 읽으세요 — 그 값이 곧 해결책입니다.
• SSL Check로 오리진이 443에서 실제로 TLS를 서빙하는지 확인하세요. 그래야 Upgrade: TLS/... 응답이 깨진 리스너가 아니라 충족 가능한 요구임을 알 수 있습니다.

Resolution Checklist

• 426 응답의 Upgrade 헤더를 읽으세요 — 서버가 기대하는 정확한 프로토콜을 알려줍니다.
• TLS를 지정하면 평문 HTTP 대신 요청을 https://로 바꾸거나 업그레이드 핸드셰이크를 추가하세요.
• h2나 websocket을 지정하면 클라이언트에서 HTTP/2를 켜거나 WebSocket 핸드셰이크를 수행하세요.
• HTTP 클라이언트·SDK가 평문이나 HTTP/1.1 전용에 고정돼 있지 않은지 확인하세요.
• 지정된 프로토콜로 요청을 다시 보내 101 Switching Protocols 또는 정상 2xx가 오는지 확인하세요.
• HTTP Check를 다시 돌려 응답이 더 이상 426이 아님을 확인하세요.

When to Escalate

• 서버가 Upgrade 헤더 없이 426을 보내면 명세 위반입니다. 응답이 반드시 알려줘야 할 것을 숨기고 있으므로 엔드포인트 담당자에게 알리세요.
• Upgrade 헤더가 지정한 프로토콜을 이미 쓰는데도 426이 나온다면, 오리진 앞의 프록시나 게이트웨이가 요청을 재작성하고 있을 가능성이 큽니다. 해당 계층 운영자에게 에스컬레이션하세요.