XMLHttpRequest.setRequestHeader() — Methode · JavaScript-Referenz

Signatur

XMLHttpRequest.prototype.setRequestHeader(header, value)

Beschreibung

Mit setRequestHeader() fügst du einer XMLHttpRequest-Anfrage eigene HTTP-Header hinzu, z. B. Content-Type, Authorization, Accept oder anwendungsspezifische Header wie X-Requested-With. Die Methode muss nach open() und vor send() aufgerufen werden, sonst wird eine InvalidStateError-DOMException ausgelöst.

Wird derselbe Header mehrfach gesetzt, überschreibt der Browser den Wert nicht, sondern hängt die Werte an: Sie werden durch ein Komma und ein Leerzeichen getrennt zu einem einzigen Header zusammengefügt (z. B. X-Test: a, b). Einen einmal gesetzten Header kannst du nicht mehr entfernen oder zurücksetzen – nur mit einem neuen open()-Aufruf beginnt die Anfrage von vorn.

Bestimmte Header gelten als verbotene Anforderungsheader (forbidden request headers), etwa Host, Cookie, Content-Length, Origin, Referer oder alle Header mit dem Präfix Sec- bzw. Proxy-. Diese verwaltet ausschließlich der Browser; Versuche, sie zu setzen, werden stillschweigend ignoriert.

Für neuen Code ist meist die Fetch-API mit einem Headers-Objekt komfortabler. XMLHttpRequest bleibt aber relevant, z. B. für Upload-Fortschrittsanzeigen über xhr.upload.onprogress oder in Bestandscode.

Parameter

Name	Typ	Default	Beschreibung
$header Pflicht	string		Name des Headers, z. B. `"Content-Type"`. Groß-/Kleinschreibung spielt keine Rolle. Muss ein gültiger HTTP-Token sein, sonst wird ein `SyntaxError` geworfen.
$value Pflicht	string		Wert des Headers. Führende und abschließende Leerzeichen werden entfernt; ungültige Zeichen (z. B. Zeilenumbrüche) führen zu einem `SyntaxError`. Nicht-String-Werte werden in einen String umgewandelt.

Beispiele

JSON per POST mit Content-Type senden

const xhr = new XMLHttpRequest();
xhr.open('POST', '/api/benutzer');
// Header zwischen open() und send() setzen
xhr.setRequestHeader('Content-Type', 'application/json; charset=utf-8');
xhr.setRequestHeader('Accept', 'application/json');

xhr.onload = () => {
  console.log(xhr.status, JSON.parse(xhr.responseText));
};
xhr.onerror = () => console.error('Netzwerkfehler');

xhr.send(JSON.stringify({ name: 'Anna', rolle: 'admin' }));

201 { id: 42, name: 'Anna', rolle: 'admin' }

Bearer-Token für eine geschützte API mitsenden

const ladeProfil = (token) => new Promise((resolve, reject) => {
  const xhr = new XMLHttpRequest();
  xhr.open('GET', 'https://api.example.com/profil');
  xhr.setRequestHeader('Authorization', `Bearer ${token}`);
  xhr.responseType = 'json';
  xhr.onload = () => (xhr.status === 200 ? resolve(xhr.response) : reject(new Error(`HTTP ${xhr.status}`)));
  xhr.onerror = () => reject(new Error('Netzwerkfehler'));
  xhr.send();
});

ladeProfil('abc123')
  .then((profil) => console.log(profil.name))
  .catch(console.error);

Anna

Mehrfaches Setzen hängt Werte an

const xhr = new XMLHttpRequest();
xhr.open('GET', '/api/test');
xhr.setRequestHeader('X-Feature', 'dunkelmodus');
xhr.setRequestHeader('X-Feature', 'beta');
// Gesendet wird: X-Feature: dunkelmodus, beta
xhr.send();

Fehler bei falscher Reihenfolge abfangen

const xhr = new XMLHttpRequest();
try {
  // open() wurde noch nicht aufgerufen
  xhr.setRequestHeader('Accept', 'text/plain');
} catch (err) {
  console.log(err.name);
}

InvalidStateError

// Wichtig · Fallstricke

Reihenfolge: Aufruf vor open() oder nach send() löst InvalidStateError aus.
Kein Überschreiben: Doppeltes Setzen verkettet die Werte mit , . Das kann bei Content-Type oder Authorization zu ungültigen Headern führen – jeden Header nur einmal setzen.
Verbotene Header wie Cookie, Host, Content-Length, Referer, Origin, Connection oder Sec-* werden stillschweigend ignoriert. Cookies sendest du bei Cross-Origin-Anfragen stattdessen mit xhr.withCredentials = true.
CORS: Eigene Header (alles außer den CORS-safelisted Headern wie Accept, Accept-Language, Content-Language und Content-Type mit text/plain, multipart/form-data oder application/x-www-form-urlencoded) lösen bei Cross-Origin-Anfragen einen Preflight (OPTIONS) aus. Der Server muss sie in Access-Control-Allow-Headers erlauben, sonst schlägt die Anfrage fehl.
FormData: Beim Senden von FormData kein Content-Type manuell setzen – der Browser erzeugt ihn inklusive boundary automatisch.
Sicherheit: Header-Werte aus Benutzereingaben nie ungeprüft übernehmen; Tokens nicht im Klartext loggen.
Die Methode wird von allen Browsern unterstützt; sie ist in Web Workern verfügbar, nicht aber in Service Workern (dort nur fetch()).

Siehe auch

XMLHttpRequest XMLHttpRequest.open() XMLHttpRequest.send() XMLHttpRequest.getResponseHeader() XMLHttpRequest.withCredentials Headers