XMLHttpRequest.statusText — Eigenschaft · JavaScript-Referenz

Signatur

XMLHttpRequest.statusText

Beschreibung

Die schreibgeschützte Eigenschaft statusText eines XMLHttpRequest-Objekts enthält die Statusnachricht (engl. reason phrase), die der Server in der Statuszeile der HTTP-Antwort mitsendet. Bei der Antwortzeile HTTP/1.1 404 Not Found liefert statusText also "Not Found", während status den numerischen Code 404 enthält.

Solange die Anfrage noch nicht abgeschickt wurde oder noch keine Header empfangen wurden (readyState ist UNSENT oder OPENED), ist der Wert ein leerer String. Ab HEADERS_RECEIVED (readyState === 2) steht die Statusnachricht zur Verfügung. Auch bei Netzwerkfehlern, CORS-Blockaden oder abgebrochenen Anfragen bleibt statusText leer.

Die Eigenschaft eignet sich vor allem für Logging und menschenlesbare Fehlermeldungen. Für Programmlogik (Verzweigungen nach Erfolg/Fehler) sollte man sich immer auf den numerischen status stützen, da die Statusnachricht vom Server frei gewählt werden kann und bei HTTP/2 und HTTP/3 grundsätzlich fehlt.

Rückgabewert

Typ

string

Beschreibung

Die Statusnachricht der HTTP-Antwort (z. B. "OK", "Not Found"). Leerer String, wenn noch keine Antwort-Header empfangen wurden, bei Netzwerkfehlern oder wenn das Protokoll keine Statusnachricht überträgt (HTTP/2, HTTP/3).

Beispiele

Status und Statusnachricht ausgeben

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

xhr.addEventListener('load', () => {
  console.log(`${xhr.status} ${xhr.statusText}`);
});

xhr.send();

200 OK

Aussagekräftige Fehlermeldung mit Fallback

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 {
      // Bei HTTP/2 ist statusText leer – daher Fallback
      const text = xhr.statusText || 'Unbekannter Fehler';
      reject(new Error(`HTTP ${xhr.status}: ${text}`));
    }
  };
  xhr.onerror = () => reject(new Error('Netzwerkfehler'));
  xhr.send();
});

try {
  await ladeJson('/api/gibt-es-nicht');
} catch (err) {
  console.error(err.message);
}

HTTP 404: Not Found

Wert im Verlauf von readyState beobachten

const xhr = new XMLHttpRequest();
console.log('UNSENT:', JSON.stringify(xhr.statusText));

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

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

xhr.send();

UNSENT: "" OPENED: "" readyState 2: "OK" readyState 3: "OK" readyState 4: "OK"

// Wichtig · Fallstricke

HTTP/2 und HTTP/3: Diese Protokolle übertragen keine Statusnachricht. statusText ist dann meist ein leerer String – verlasse dich nie darauf, dass ein Text vorhanden ist.
Nicht für Logik verwenden: Die Nachricht ist frei wählbar (z. B. "Alles gut" statt "OK"). Vergleiche immer status, nicht statusText.
Netzwerk- und CORS-Fehler: status ist 0 und statusText leer; Details zur Ursache sind aus Sicherheitsgründen nicht einsehbar.
Sicherheit: Da der Wert vom Server stammt, nicht ungeprüft per innerHTML ins DOM schreiben – textContent verwenden.
Die Eigenschaft ist schreibgeschützt; Zuweisungen werden ignoriert (im Strict Mode ohne Fehler, da es ein Getter auf dem Prototyp ist, der keinen Setter hat – im Strict Mode wird ein TypeError geworfen).
Kompatibilität: in allen Browsern verfügbar; in Web Workern ebenfalls nutzbar. Für neuen Code ist fetch() mit Response.statusText die modernere Alternative.

Siehe auch

XMLHttpRequest XMLHttpRequest.status XMLHttpRequest.readyState XMLHttpRequest.getAllResponseHeaders() Response.statusText Window.status