RTCPeerConnectionIceErrorEvent.errorCode — Eigenschaft · JavaScript-Referenz

Signatur

RTCPeerConnectionIceErrorEvent.errorCode

Beschreibung

Die Eigenschaft errorCode eines RTCPeerConnectionIceErrorEvent enthält den numerischen Fehlercode, der beim Sammeln von ICE-Kandidaten aufgetreten ist. Das Ereignis wird als icecandidateerror an einer RTCPeerConnection ausgelöst, wenn eine Anfrage an einen der in iceServers konfigurierten STUN- oder TURN-Server fehlschlägt.

Die Werte folgen den STUN-Fehlercodes aus RFC 5389 bzw. RFC 8656 (TURN) und liegen im Bereich 300–699. Typische Werte sind:

401 – Unauthorized (Zugangsdaten fehlen oder sind ungültig)
403 – Forbidden
437 – Allocation Mismatch, 438 – Stale Nonce
441 – Wrong Credentials, 442 – Unsupported Transport Protocol
486 – Allocation Quota Reached, 508 – Insufficient Capacity
701 – Server nicht erreichbar bzw. keine Antwort (vom Browser selbst gesetzt, Bereich 700–799)

Die Eigenschaft eignet sich vor allem zur Diagnose von Verbindungsproblemen: falsche TURN-Anmeldedaten, blockierte Ports, Firewalls oder überlastete Server lassen sich anhand des Codes unterscheiden. Zusammen mit url, address, port und errorText ergibt sich ein vollständiges Fehlerbild für Logging und Monitoring.

Rückgabewert

Typ

number

Beschreibung

Ganzzahl (unsigned short) mit dem STUN-Fehlercode (300–699) oder einem browserseitigen Code im Bereich 700–799, z. B. 701, wenn der Server nicht erreicht wurde. Nur lesbar.

Beispiele

ICE-Fehler per addEventListener protokollieren

const pc = new RTCPeerConnection({
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' },
    { urls: 'turn:turn.example.com:3478', username: 'user', credential: 'falsch' }
  ]
});

pc.addEventListener('icecandidateerror', (event) => {
  console.warn(`ICE-Fehler ${event.errorCode} (${event.errorText}) bei ${event.url}`);
});

// Kandidatensammlung anstoßen
pc.createDataChannel('test');
pc.createOffer().then((offer) => pc.setLocalDescription(offer));

ICE-Fehler 401 (Unauthorized) bei turn:turn.example.com:3478?transport=udp

Fehlercodes in verständliche Meldungen übersetzen (on-Property)

const describeIceError = (code) => {
  if (code === 401 || code === 441) return 'TURN-Zugangsdaten ungültig';
  if (code === 486 || code === 508) return 'TURN-Server ausgelastet';
  if (code >= 700 && code <= 799) return 'Server nicht erreichbar (Firewall/Netzwerk?)';
  if (code >= 300 && code <= 699) return `STUN/TURN-Fehler ${code}`;
  return 'Unbekannter Fehler';
};

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.unerreichbar.example:3478' }]
});

pc.onicecandidateerror = (event) => {
  console.log(describeIceError(event.errorCode));
};

pc.createDataChannel('probe');
await pc.setLocalDescription(await pc.createOffer());

Server nicht erreichbar (Firewall/Netzwerk?)

Fehler pro Server sammeln und an Monitoring senden

const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'turn:turn.example.com:443?transport=tcp', username: 'u', credential: 'p' }]
});
const iceErrors = [];

pc.addEventListener('icecandidateerror', ({ errorCode, errorText, url, address, port }) => {
  iceErrors.push({ errorCode, errorText, url, address, port });
});

pc.addEventListener('icegatheringstatechange', () => {
  if (pc.iceGatheringState === 'complete' && iceErrors.length > 0) {
    navigator.sendBeacon('/api/ice-errors', JSON.stringify(iceErrors));
    console.log(`${iceErrors.length} ICE-Fehler gemeldet`);
  }
});

pc.createDataChannel('x');
await pc.setLocalDescription(await pc.createOffer());

1 ICE-Fehler gemeldet

// Wichtig · Fallstricke

Kein fataler Fehler: Ein icecandidateerror bedeutet nur, dass ein Server bzw. Transportweg fehlgeschlagen ist. Die Verbindung kann über andere Kandidaten trotzdem zustande kommen – den Verbindungsstatus daher über iceConnectionState/connectionState prüfen, nicht allein über dieses Ereignis.
Code 701: Der Wert stammt nicht vom Server, sondern vom Browser (Zeitüberschreitung, DNS-Fehler, blockierter Port). Häufig tritt er bei jedem nicht erreichbaren Server und jeder Netzwerkschnittstelle mehrfach auf – Logs ggf. deduplizieren.
Browser-Unterschiede: Nicht alle Browser feuern das Ereignis in denselben Situationen, und der errorText variiert. Vor Nutzung per 'onicecandidateerror' in RTCPeerConnection.prototype prüfen.
Datenschutz: Die zugehörigen Eigenschaften address/port können lokale IP-Adressen enthalten (bzw. aus Datenschutzgründen verschleiert oder null sein) – beim Versand an Server-Logs beachten.
Die veraltete Eigenschaft hostCandidate wurde durch address und port ersetzt.

Siehe auch

RTCPeerConnectionIceErrorEvent RTCPeerConnectionIceErrorEvent.errorText RTCPeerConnectionIceErrorEvent.url RTCPeerConnectionIceErrorEvent.address RTCPeerConnection