← 免費工具

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

    這台主機上沒有這個金鑰的應用。

    怎麼處理: 檢查應用金鑰和主機(或 cluster):一個服務或區域的金鑰不能用在另一個。

    不會用相同設定重新連線
  • 4003 Application disabled

    應用存在,但已停用。

    怎麼處理: 在應用的管理頁重新啟用,或檢查帳號的帳務狀態。

    不會用相同設定重新連線
  • 4004 Over connection quota

    應用開啟的連線數已達方案上限。

    怎麼處理: 等其他連線關閉、關掉不需要的分頁,或改用連線數更多的方案。

    不會用相同設定重新連線
  • 4005 Path not found

    網址路徑不是 /app/APP_KEY。

    怎麼處理: 檢查 WebSocket 路徑:代理伺服器和錯誤的 wsPath 設定常造成這個問題。

    不會用相同設定重新連線
  • 4006 Invalid version string format

    用戶端送出的版本伺服器讀不懂。

    怎麼處理: 使用官方用戶端程式庫,或在網址加上 protocol=7。

    不會用相同設定重新連線
  • 4007 Unsupported protocol version

    伺服器不支援用戶端要求的協定版本。

    怎麼處理: 更新用戶端程式庫;目前的協定版本是 7。

    不會用相同設定重新連線
  • 4008 No protocol version supplied

    網址裡沒有 protocol 參數。

    怎麼處理: 在網址加上 ?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:私人用途,意思由送出它的應用或服務決定。

訂閱錯誤

私人或 presence 頻道訂閱失敗時不會關閉連線,用戶端會收到 pusher:subscription_error。其中的 AuthError 幾乎都是授權端點回傳的簽章對不上:密鑰、socket ID、頻道名稱或 channel_data 和簽章時用的不一樣。

檢查簽章

用 WebSocket 測試工具測試連線 → · 訊息大小與其他限制 →