XMLHttpRequestEventTarget: error — Ereignis · JavaScript-Referenz

Signatur

xhr.addEventListener("error", handler) / xhr.onerror = handler

Beschreibung

Das error-Ereignis gehört zur Schnittstelle XMLHttpRequestEventTarget. Es wird ausgelöst, wenn eine Anfrage mit XMLHttpRequest auf Netzwerkebene scheitert. Typische Ursachen sind ein nicht erreichbarer Server, DNS-Fehler, ein abgebrochener Verbindungsaufbau, eine CORS-Ablehnung oder ein Offline-Zustand. Der Handler erhält ein ProgressEvent.

Wichtig: HTTP-Fehlerstatus wie 404 oder 500 lösen kein error-Ereignis aus. Der Server hat ja geantwortet, deshalb feuert load. Serverfehler prüft man daher im load-Handler über xhr.status.

Die Reihenfolge der Ereignisse im Fehlerfall ist: readystatechange (mit readyState 4), dann error, danach loadend. Das Ereignis gibt es auch an xhr.upload. Dort meldet es Fehler beim Hochladen des Anfrage-Bodys.

Man registriert den Handler mit addEventListener("error", handler) oder über die Eigenschaft onerror. Er sollte vor dem Aufruf von send() gesetzt werden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"error"` (nur bei `addEventListener`).
$handler Pflicht	(event: ProgressEvent) => void		Callback, der ein `ProgressEvent` erhält. Dessen Eigenschaften `loaded`, `total` und `lengthComputable` geben den Fortschritt zum Zeitpunkt des Fehlers an.
$options	boolean\|AddEventListenerOptions	false	Optionen wie `once` oder `signal` (nur bei `addEventListener`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt undefined zurück. Der Rückgabewert des Handlers wird ignoriert.

Beispiele

Netzwerkfehler mit addEventListener abfangen

const xhr = new XMLHttpRequest();
xhr.open('GET', 'https://nicht-existent.example/api/daten');

xhr.addEventListener('load', () => {
  console.log('Antwort erhalten, Status:', xhr.status);
});

xhr.addEventListener('error', (event) => {
  // status ist bei Netzwerkfehlern immer 0
  console.error('Netzwerkfehler! Status:', xhr.status, 'Typ:', event.type);
});

xhr.send();

Netzwerkfehler! Status: 0 Typ: error

onerror-Eigenschaft und HTTP-Fehler unterscheiden

const ladeJson = (url) => new Promise((resolve, reject) => {
  const xhr = new XMLHttpRequest();
  xhr.open('GET', url);
  xhr.responseType = 'json';

  xhr.onload = () => {
    if (xhr.status >= 200 && xhr.status < 300) {
      resolve(xhr.response);
    } else {
      // 404/500 landen hier, nicht in onerror
      reject(new Error(`HTTP-Fehler ${xhr.status}`));
    }
  };
  xhr.onerror = () => reject(new Error('Netzwerkfehler oder CORS-Blockade'));
  xhr.send();
});

try {
  const daten = await ladeJson('/api/benutzer');
  console.log(daten);
} catch (err) {
  console.error(err.message);
}

z. B. "Netzwerkfehler oder CORS-Blockade" oder "HTTP-Fehler 404"

Upload-Fehler an xhr.upload überwachen und Listener entfernen

const datei = new Blob(['Hallo Welt'], { type: 'text/plain' });
const xhr = new XMLHttpRequest();

const beiUploadFehler = () => {
  console.error('Upload fehlgeschlagen');
};

xhr.upload.addEventListener('error', beiUploadFehler);
xhr.addEventListener('loadend', () => {
  // Aufräumen, egal ob Erfolg oder Fehler
  xhr.upload.removeEventListener('error', beiUploadFehler);
  console.log('Anfrage beendet');
});

xhr.open('POST', '/upload');
xhr.send(datei);

Upload fehlgeschlagen (bei Verbindungsabbruch) Anfrage beendet

// Wichtig · Fallstricke

Kein Ereignis bei HTTP-Fehlern: Antworten mit 4xx oder 5xx lösen load aus, nicht error. Den Status prüft man immer im load-Handler.
Kaum Details verfügbar: Aus Sicherheitsgründen erfährt das Skript nicht, warum die Anfrage gescheitert ist. xhr.status ist 0, und es gibt keine Fehlermeldung. Ob ein CORS-Problem vorlag, sieht man nur in der Entwicklerkonsole.
Abbruch und Zeitüberschreitung: xhr.abort() löst abort aus, eine überschrittene timeout-Zeit löst timeout aus, jeweils statt error. Wer alle Fälle behandeln will, nutzt zusätzlich loadend.
Synchrone Anfragen: Bei open(..., false) wird statt des Ereignisses eine NetworkError-DOMException von send() geworfen.
Das Ereignis wird in allen Browsern unterstützt. Für neuen Code empfiehlt sich meist fetch(): Es lehnt das Promise bei Netzwerkfehlern mit einem TypeError ab.

Siehe auch

load loadend abort timeout ProgressEvent