XMLHttpRequest.status — Eigenschaft · JavaScript-Referenz

Signatur

XMLHttpRequest.status

Beschreibung

Die Eigenschaft status enthält den HTTP-Statuscode, den der Server mit seiner Antwort gesendet hat, z. B. 200 für „OK“, 404 für „Not Found“ oder 500 für einen Serverfehler. So könnt ihr nach Abschluss einer Anfrage zwischen Erfolg und Fehler unterscheiden.

Solange die Anfrage noch nicht abgeschlossen ist oder ein Fehler aufgetreten ist, liefert status den Wert 0. Das gilt für die Zustände UNSENT und OPENED, bei Netzwerkfehlern, bei durch CORS blockierten Anfragen, bei Zeitüberschreitung (timeout) und nach abort(). Ab dem Zustand HEADERS_RECEIVED (readyState === 2) steht der echte Statuscode zur Verfügung.

Wichtig: Ein XMLHttpRequest meldet auch bei 4xx- und 5xx-Antworten das Ereignis load – ein HTTP-Fehler ist aus Sicht der API kein Netzwerkfehler. Den Statuscode müsst ihr deshalb immer selbst prüfen, typischerweise mit xhr.status >= 200 && xhr.status < 300.

Den zugehörigen Text der Statuszeile (z. B. "Not Found") liefert statusText. Bei HTTP/2 ist dieser allerdings meist leer, deshalb solltet ihr euch auf den numerischen status verlassen.

Rückgabewert

Typ

number

Beschreibung

Ein unsigned short mit dem HTTP-Statuscode (z. B. 200, 301, 404) oder 0, wenn die Anfrage noch nicht abgeschlossen ist oder fehlgeschlagen ist.

Beispiele

Statuscode im load-Ereignis prüfen

const xhr = new XMLHttpRequest();
xhr.open('GET', '/api/benutzer/42');
xhr.responseType = 'json';

xhr.addEventListener('load', () => {
  if (xhr.status >= 200 && xhr.status < 300) {
    console.log('Benutzer geladen:', xhr.response);
  } else if (xhr.status === 404) {
    console.warn('Benutzer nicht gefunden');
  } else {
    console.error(`Serverfehler: ${xhr.status} ${xhr.statusText}`);
  }
});

xhr.addEventListener('error', () => {
  // Netzwerk- oder CORS-Fehler: status ist hier 0
  console.error('Netzwerkfehler, status =', xhr.status);
});

xhr.send();

Benutzer nicht gefunden

Verlauf von status über die readyState-Phasen

const xhr = new XMLHttpRequest();
console.log('UNSENT:', xhr.status);

xhr.open('GET', '/index.html');
console.log('OPENED:', xhr.status);

xhr.onreadystatechange = () => {
  console.log(`readyState ${xhr.readyState}:`, xhr.status);
};

xhr.send();

UNSENT: 0 OPENED: 0 readyState 2: 200 readyState 3: 200 readyState 4: 200

XMLHttpRequest als Promise mit Statusprüfung

const request = (method, url) =>
  new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open(method, url);
    xhr.timeout = 5000;
    xhr.onload = () => {
      if (xhr.status >= 200 && xhr.status < 300) {
        resolve(xhr.responseText);
      } else {
        reject(new Error(`HTTP ${xhr.status}`));
      }
    };
    xhr.onerror = () => reject(new Error('Netzwerkfehler (status 0)'));
    xhr.ontimeout = () => reject(new Error('Zeitüberschreitung'));
    xhr.send();
  });

try {
  const text = await request('GET', '/daten.txt');
  console.log(text);
} catch (err) {
  console.error(err.message);
}

HTTP 500

// Wichtig · Fallstricke

Status 0 ist kein HTTP-Code: Er steht für „keine Antwort“, also für nicht gesendete oder abgebrochene Anfragen, Netzwerkfehler, Zeitüberschreitung oder CORS-Blockade. Aus Sicherheitsgründen könnt ihr eine CORS-Blockade nicht von einem echten Netzwerkfehler unterscheiden.
HTTP-Fehler lösen load aus, nicht error: Prüft status deshalb immer selbst.
Weiterleitungen: Die Codes 301/302/307/308 bekommt ihr normalerweise nicht zu sehen, weil der Browser Weiterleitungen automatisch folgt. status zeigt dann den Code des Endziels, die Ziel-URL steht in responseURL.
file://-URLs: Einige Browser liefern hier bei Erfolg 0 statt 200.
Kompatibilität: Wird von allen Browsern unterstützt. Sehr alte Internet-Explorer-Versionen gaben bei 204 fälschlich 1223 zurück. Für neuen Code ist fetch() mit Response.status und Response.ok meist die modernere Wahl.

Siehe auch

XMLHttpRequest XMLHttpRequest.statusText XMLHttpRequest.readyState XMLHttpRequest.responseURL Response.status