WebSocket 종료 코드와 Pusher 오류 코드
각 코드의 의미와 해결 방법: 표준 WebSocket 종료 코드(1000–1015)와 Pusher 프로토콜의 오류 코드(4000–4399)입니다. Hibira와 다른 Pusher 호환 서비스도 같은 코드를 보냅니다.
Pusher 프로토콜 코드
Pusher 서버는 코드와 이유가 담긴 pusher:error 메시지를 보낸 다음, 같은 코드로 연결을 닫습니다. 코드의 범위가 클라이언트의 다음 동작을 정합니다.
4000 SSL only
이 앱은 암호화된 연결만 받습니다.
해결 방법: wss://로 연결하세요(pusher-js에서는 forceTLS: true).
같은 설정으로는 다시 연결하지 않음4001 Application does not exist
이 호스트에 이 키를 쓰는 앱이 없습니다.
해결 방법: 앱 키와 호스트(또는 클러스터)를 확인하세요. 한 서비스나 리전의 키는 다른 곳에서 쓸 수 없습니다.
같은 설정으로는 다시 연결하지 않음4003 Application disabled
앱은 있지만 꺼져 있습니다.
해결 방법: 대시보드에서 앱을 다시 켜거나, 계정의 결제 상태를 확인하세요.
같은 설정으로는 다시 연결하지 않음4004 Over connection quota
앱의 연결 수가 플랜 한도에 이르렀습니다.
해결 방법: 다른 연결이 닫히길 기다리거나, 필요 없는 탭을 닫거나, 연결 수가 더 많은 플랜으로 바꾸세요.
같은 설정으로는 다시 연결하지 않음4005 Path not found
URL 경로가 /app/APP_KEY가 아닙니다.
해결 방법: WebSocket 경로를 확인하세요. 프록시나 잘못된 wsPath 설정이 흔한 원인입니다.
같은 설정으로는 다시 연결하지 않음4006 Invalid version string format
클라이언트가 보낸 버전을 서버가 읽을 수 없습니다.
해결 방법: 공식 클라이언트 라이브러리를 쓰거나, URL에 protocol=7을 붙이세요.
같은 설정으로는 다시 연결하지 않음4007 Unsupported protocol version
클라이언트가 요청한 프로토콜 버전을 서버가 지원하지 않습니다.
해결 방법: 클라이언트 라이브러리를 업데이트하세요. 현재 프로토콜은 7입니다.
같은 설정으로는 다시 연결하지 않음4008 No protocol version supplied
URL에 protocol 파라미터가 없습니다.
해결 방법: URL에 ?protocol=7을 붙이거나, 공식 클라이언트 라이브러리를 쓰세요.
같은 설정으로는 다시 연결하지 않음4009 Connection is unauthorized
서버가 이 연결을 거부했습니다. Hibira에서는 페이지의 오리진이 허용되지 않은 경우가 가장 많습니다.
해결 방법: 사이트의 오리진(스킴, 호스트, 포트)을 앱의 허용 오리진에 추가하세요. 연결이 닫히기 전에 오는 pusher:error 메시지에 어떤 검사에서 실패했는지 나옵니다.
같은 설정으로는 다시 연결하지 않음4100 Over capacity
서버가 바쁘거나, 한 주소에서 한꺼번에 너무 많은 연결이 왔습니다.
해결 방법: 대부분은 아무것도 할 필요가 없습니다. 클라이언트가 백오프 후 다시 시도합니다. 계속 일어나면 모든 클라이언트가 동시에 다시 연결하지 않도록 시점을 분산하세요.
백오프 후 다시 연결함4200 Generic reconnect immediately
서버가 클라이언트에 다시 연결하라고 요청했습니다. 예를 들어 서버가 재시작하는 중입니다.
해결 방법: 할 일 없음: 클라이언트가 바로 다시 연결합니다.
바로 다시 연결함4201 Pong reply not received
서버가 ping을 보냈지만 제때 pong이 오지 않았습니다.
해결 방법: 대개 탭이 절전 상태이거나 모바일 네트워크가 약할 때입니다. 클라이언트를 직접 만들었다면 pusher:ping에 pusher:pong으로 답하세요.
바로 다시 연결함4202 Closed after inactivity
연결이 너무 오래 유휴 상태였습니다.
해결 방법: 할 일 없음: 클라이언트가 다시 연결합니다. 클라이언트의 activity timeout을 서버보다 짧게 두세요.
바로 다시 연결함4301 Client event rejected due to rate limit
이 연결이 클라이언트 이벤트를 너무 빨리 많이 보내서 하나가 버려졌습니다(Hibira에서는 하루 메시지 한도를 다 쓴 경우도 해당). 연결은 유지됩니다.
해결 방법: 초당 보내는 클라이언트 이벤트를 줄이세요. 예를 들어 입력 중 표시나 커서 이벤트를 스로틀링합니다.
연결이 유지됨
표준 WebSocket 코드
WebSocket 표준(RFC 6455)에서 정한 코드로, 모든 WebSocket 서버에 해당합니다.
1000 Normal Closure
연결을 의도적으로 닫았고, 작업이 끝났습니다.
해결 방법: 고칠 것이 없습니다.
1001 Going Away
페이지를 닫거나 새로 고쳤거나, 서버가 종료되는 중입니다.
해결 방법: 고칠 것이 없습니다. 페이지나 서버가 돌아오면 다시 연결하세요.
1002 Protocol Error
한쪽이 WebSocket 프로토콜에 어긋나는 프레임을 보냈습니다.
해결 방법: 트래픽을 바꿔 쓰는 프록시가 있는지, 클라이언트와 서버 라이브러리가 서로 맞지 않는지 확인하세요.
1003 Unsupported Data
상대가 받을 수 없는 종류의 메시지입니다. 예를 들어 텍스트만 받는 서버에 보낸 바이너리.
해결 방법: 서버가 기대하는 종류로 보내세요(Pusher 서버는 JSON 텍스트를 받습니다).
1005 No Status Received
종료 프레임에 코드가 없었습니다. 브라우저가 보고하는 값이며, 실제로 전송되지는 않습니다.
해결 방법: 이 코드만으로는 원인을 알 수 없습니다. 서버가 연결을 닫을 때 남긴 로그를 확인하세요.
1006 Abnormal Closure
종료 프레임 없이 연결이 끊겼습니다. 네트워크, TLS, 프록시 또는 서버가 연결을 끝냈습니다. 브라우저가 보고하는 값이며, 실제로 전송되지는 않습니다.
해결 방법: 호스트와 포트, wss://와 ws://를 맞게 썼는지, 인증서, 프록시나 로드 밸런서의 유휴 시간 제한을 확인하세요(하트비트는 유휴 연결이 끊기기 전보다 짧은 간격으로 보냅니다). 브라우저에서는 대개 콘솔에 원인이 나옵니다.
1007 Invalid Frame Payload Data
텍스트 메시지가 올바른 UTF-8이 아닙니다.
해결 방법: 텍스트를 UTF-8로 인코딩하거나 바이너리로 보내세요.
1008 Policy Violation
서버가 자체 규칙(인증이나 오리진 검사 등)에 따라 메시지나 연결을 거부했습니다.
해결 방법: 서버의 규칙과 종료 이유를 확인하세요.
1009 Message Too Big
메시지가 상대가 받을 수 있는 크기보다 큽니다.
해결 방법: 메시지를 줄이거나, 큰 메시지는 나눠서 보내세요.
1010 Mandatory Extension
클라이언트에 필요한 확장을 서버가 받아들이지 않았습니다.
해결 방법: 클라이언트에서 그 확장을 끄거나, 서버에서 켜세요.
1011 Internal Error
서버에 예기치 않은 오류가 났습니다.
해결 방법: 서버 로그를 확인하고, 백오프하며 다시 연결하세요.
1012 Service Restart
서버가 재시작하는 중입니다.
해결 방법: 짧은 무작위 시간을 기다린 뒤 다시 연결하세요.
1013 Try Again Later
서버가 지금 과부하 상태입니다.
해결 방법: 백오프하며 다시 연결하세요.
1014 Bad Gateway
게이트웨이나 프록시가 뒤쪽 서버에서 잘못된 응답을 받았습니다.
해결 방법: 프록시 뒤의 서버를 확인하세요.
1015 TLS Handshake
TLS 핸드셰이크에 실패했습니다. 예를 들어 클라이언트가 신뢰하지 않는 인증서입니다. 브라우저가 보고하는 값이며, 실제로 전송되지는 않습니다.
해결 방법: 인증서 체인, 호스트 이름, 만료일을 확인하세요.
코드 범위
- 1000–2999: WebSocket 표준용 예약 범위입니다. 이 코드는 아직 할당되지 않았습니다.
- 3000–3999: 라이브러리와 프레임워크용 등록 범위입니다. 쓰고 있는 것을 확인하세요.
- 4000–4099: 이후 클라이언트가 같은 설정으로는 다시 연결하지 않는 Pusher 오류.
- 4100–4199: 이후 클라이언트가 백오프 후 다시 연결하는 Pusher 오류.
- 4200–4299: 이후 클라이언트가 바로 다시 연결하는 Pusher 오류.
- 4300–4399: 연결을 유지하는 Pusher 오류.
- 4000–4999: 비공개 용도. 의미는 보낸 애플리케이션이나 서비스가 정합니다.
구독 오류
비공개 채널이나 프레즌스 채널 구독에 실패해도 연결은 닫히지 않고, 클라이언트는 pusher:subscription_error를 받습니다. 여기서 AuthError는 거의 언제나 인증 엔드포인트가 돌려준 서명이 맞지 않는다는 뜻입니다. 시크릿, 소켓 ID, 채널 이름, channel_data 중 하나가 서명할 때와 다릅니다.