CloseEvent.code — Eigenschaft · JavaScript-Referenz

Signatur

CloseEvent.code

Beschreibung

Die schreibgeschützte Eigenschaft code des CloseEvent-Interfaces enthält den Statuscode, mit dem eine WebSocket-Verbindung beendet wurde. Das Event erhältst du im Handler für das close-Event eines WebSocket-Objekts, entweder über socket.addEventListener("close", handler) oder über socket.onclose.

Die Codes sind in RFC 6455, Abschnitt 7.4 definiert und im IANA-Register gelistet. Wichtige Werte:

1000 – normales Schließen, die Verbindung hat ihren Zweck erfüllt.
1001 – Gegenstelle geht weg (Server fährt herunter, Seite wird verlassen).
1002 – Protokollfehler.
1003 – nicht unterstützter Datentyp.
1005 – kein Statuscode übermittelt (reserviert, wird nie aktiv gesendet).
1006 – abnormales Schließen ohne Close-Frame, z. B. Netzabbruch oder fehlgeschlagener Handshake (reserviert).
1007 – ungültige Nutzdaten (z. B. kein gültiges UTF-8).
1008 – Richtlinienverstoß.
1009 – Nachricht zu groß.
1011 – interner Serverfehler.
1015 – TLS-Handshake fehlgeschlagen (reserviert).
3000–3999 – für Bibliotheken und Frameworks (bei IANA registriert); 4000–4999 – frei für anwendungsspezifische Codes.

Typischerweise wertest du code aus, um zu entscheiden, ob du automatisch neu verbindest (z. B. bei 1006 oder 1011), ob du dem Nutzer eine Fehlermeldung anzeigst oder ob das Schließen gewollt war (1000). Zusammen mit CloseEvent.reason und CloseEvent.wasClean ergibt sich ein vollständiges Bild des Verbindungsendes.

Rückgabewert

Typ

number

Beschreibung

Ganzzahliger Statuscode (unsigned short, 0–65535) des Verbindungsabbaus, z. B. 1000 für normales Schließen. Bei manuell erzeugten Events ohne Angabe: 0.

Beispiele

Schließcode mit addEventListener auswerten

const socket = new WebSocket("wss://echo.websocket.org");

socket.addEventListener("open", () => {
  // Verbindung sauber mit eigenem Code und Grund beenden
  socket.close(1000, "Arbeit erledigt");
});

socket.addEventListener("close", (event) => {
  console.log(`Code: ${event.code}, Grund: ${event.reason}, sauber: ${event.wasClean}`);
});

Code: 1000, Grund: Arbeit erledigt, sauber: true

Automatischer Reconnect mit onclose und Backoff

const RETRY_CODES = new Set([1001, 1006, 1011, 1012, 1013]);
let attempt = 0;

const connect = () => {
  const socket = new WebSocket("wss://example.com/live");

  socket.onopen = () => {
    attempt = 0;
  };

  socket.onclose = ({ code, reason }) => {
    if (RETRY_CODES.has(code)) {
      const delay = Math.min(30000, 1000 * 2 ** attempt++);
      console.warn(`Verbindung verloren (${code}), neuer Versuch in ${delay} ms`);
      setTimeout(connect, delay);
    } else if (code !== 1000) {
      console.error(`Endgültig geschlossen: ${code} ${reason}`);
    }
  };
};

connect();

Verbindung verloren (1006), neuer Versuch in 1000 ms

Anwendungsspezifische Codes (4000–4999) auswerten

const messages = {
  4001: "Sitzung abgelaufen – bitte erneut anmelden.",
  4003: "Keine Berechtigung für diesen Kanal.",
};

const socket = new WebSocket("wss://example.com/chat");

socket.addEventListener("close", (event) => {
  const text = messages[event.code] ?? `Verbindung beendet (Code ${event.code}).`;
  console.log(text);
});

Sitzung abgelaufen – bitte erneut anmelden.

CloseEvent manuell erzeugen (z. B. für Tests)

const event = new CloseEvent("close", {
  code: 4001,
  reason: "Token abgelaufen",
  wasClean: true,
});

console.log(event.code);   // 4001
console.log(new CloseEvent("close").code); // 0 (Standardwert)

4001 0

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an event.code hat keine Wirkung (im Strict Mode wirft sie einen TypeError). Den Code legst du beim Schließen über WebSocket.close(code, reason) oder beim Konstruieren über new CloseEvent("close", { code }) fest.
Erlaubte Codes bei close(): Im Browser darfst du nur 1000 oder 3000–4999 übergeben. Andere Werte führen zu einer InvalidAccessError-DOMException. Ein reason länger als 123 Byte (UTF-8) wirft einen SyntaxError.
1006 ist nicht aussagekräftig: Aus Sicherheitsgründen verrät der Browser bei fehlgeschlagenem Verbindungsaufbau (DNS-, TLS-, CORS-/Origin-Fehler, abgelehnter Handshake) keine Details – du erhältst nur 1006 mit leerem reason. Details findest du ausschließlich in der Entwicklerkonsole bzw. in Server-Logs.
1005, 1006 und 1015 werden niemals über das Netz gesendet, sondern nur lokal gemeldet.
Verlasse dich nicht ausschließlich auf code, um sauberes Schließen zu erkennen – prüfe zusätzlich wasClean.
Kompatibilität: In allen modernen Browsern sowie in Node.js (ab v22 mit globalem WebSocket) verfügbar.

Siehe auch

BlobEvent.timecode CloseEvent.reason CloseEvent.wasClean BlobEvent.data Element.role