Die API liefert plötzlich 500er: eine Checkliste

Gestern lief alles, heute antwortet die Schnittstelle mit 500 Internal Server Error. Das Formular auf der Website speichert nicht mehr, der Shop synchronisiert keine Bestellungen, die Partner-Anbindung meldet Fehler. Ein 500er sagt nur eines: Auf dem Server ist etwas schiefgegangen, das der Code nicht abgefangen hat. Was genau, verrät der Statuscode nicht.

Diese Checkliste ist in der Reihenfolge aufgebaut, in der sich die Fragen am schnellsten beantworten lassen. Sie müssen nicht jeden Punkt abarbeiten. Sobald Sie die Ursache haben, hören Sie auf.

Zuerst: Ist es wirklich ein 500?

Verschiedene 5xx-Codes bedeuten Verschiedenes, und die Fehlersuche beginnt an unterschiedlichen Stellen:

• 500 Internal Server Error: Ihre Anwendung hat einen Fehler geworfen.
• 502 Bad Gateway: Ein vorgeschalteter Proxy oder Load Balancer hat keine gültige Antwort von Ihrer Anwendung bekommen, etwa weil sie abgestürzt ist.
• 503 Service Unavailable: Der Dienst ist überlastet, im Wartungsmodus oder nicht gestartet.
• 504 Gateway Timeout: Die Anwendung hat zu lange gebraucht.

Prüfen Sie den echten Statuscode und die Antwort mit curl:

curl -i -X POST https://api.example.de/v1/bestellungen \
  -H "Content-Type: application/json" \
  -d '{"id": 123}'

-i zeigt die Header mit. Achten Sie auf eine Request-ID wie x-request-id oder ähnlich. Mit ihr finden Sie die passende Zeile im Log.

Die ersten zehn Minuten

1. Betrifft es alle Anfragen oder nur bestimmte? Rufen Sie einen einfachen Endpunkt auf, etwa einen Health-Check. Funktioniert der, ist die Anwendung grundsätzlich erreichbar, und der Fehler liegt in einem bestimmten Pfad.
2. Seit wann? Der Zeitpunkt des ersten Fehlers ist die wertvollste Information. Schauen Sie in Monitoring, Logs oder in die erste Fehlermeldung eines Nutzers.
3. Was ist zu diesem Zeitpunkt passiert? Deployment, Konfigurationsänderung, Paket-Update, Datenbank-Migration, Zertifikatswechsel, Änderung bei einem Drittanbieter.
4. Gibt es einen schnellen Weg zurück? Wenn ein Deployment kurz vor dem ersten Fehler lag, ist ein Rollback auf die vorherige Version oft der schnellste Weg, den Betrieb wiederherzustellen. Die Ursache wird danach in Ruhe gesucht.

Die Logs lesen

Ohne Logs ist jede Fehlersuche Raten. Wo sie liegen, hängt von Ihrer Plattform ab: im Dashboard des Hosters, in einem Dienst wie Sentry, in journalctl auf einem eigenen Server oder in den Container-Logs.

# Docker
docker logs --since 1h mein-api-container 2>&1 | grep -i error

# systemd
journalctl -u mein-api --since "1 hour ago"

Gesucht ist ein Stacktrace oder eine Fehlermeldung zum Zeitpunkt der fehlgeschlagenen Anfrage. Wenn das Log nur „500“ ohne Details zeigt, fehlt ein zentraler Error-Handler, der unbehandelte Fehler mit Stacktrace protokolliert. Das ist der erste Punkt, der nach der akuten Störung behoben werden sollte.

Die Checkliste

Code und Deployment

• Gab es kurz vor dem ersten Fehler ein Deployment? Was hat sich im Diff geändert?
• Wurden Abhängigkeiten aktualisiert, auch indirekt, weil der Lockfile neu erzeugt wurde?
• Läuft die Anwendung mit derselben Laufzeitversion (Node.js, PHP, Python) wie vorher?
• Wurde eine Datenbank-Migration ausgeführt, die zum Code passt, oder fehlt sie?

Konfiguration und Geheimnisse

• Sind alle Umgebungsvariablen gesetzt? Eine fehlende Variable führt oft erst beim ersten Zugriff zum Fehler.
• Ist ein API-Schlüssel, Token oder Passwort abgelaufen oder rotiert worden?
• Ist ein TLS-Zertifikat abgelaufen, das die Anwendung für ausgehende Verbindungen braucht?

Datenbank

• Ist die Datenbank erreichbar?
• Ist der Connection-Pool erschöpft? Typische Meldungen enthalten „too many connections“ oder Timeouts beim Verbindungsaufbau.
• Ist der Speicherplatz voll?
• Gibt es lange laufende Abfragen oder Sperren, die andere blockieren?

Eingangsdaten

• Tritt der Fehler nur bei bestimmten Daten auf, etwa Umlauten, leeren Feldern, sehr großen Werten, einem bestimmten Kunden?
• Hat ein aufrufendes System sein Format geändert, etwa ein Datum als String statt als Zahl?

Ein 500er bei ungültigen Eingaben ist übrigens selbst ein Fehler. Die korrekte Antwort wäre ein 4xx-Code mit verständlicher Meldung.

Drittanbieter

• Ruft der Endpunkt einen externen Dienst auf: Zahlungsanbieter, CRM, Versanddienst, KI-Schnittstelle?
• Meldet dieser Dienst auf seiner Statusseite eine Störung?
• Hat er seine API-Version geändert oder eine alte Version abgeschaltet?
• Greift ein Rate-Limit? Externe Dienste antworten dann meist mit 429, und Ihr Code reicht das als 500 weiter, wenn er den Fall nicht behandelt.

Ressourcen

• Arbeitsspeicher: Wird der Prozess wegen Speichermangels beendet und neu gestartet?
• Festplatte: Sind Log- oder Temp-Verzeichnisse voll gelaufen?
• Zeitlimits: Bricht eine Serverless-Funktion wegen einer Ausführungszeit-Grenze ab?

Serverless und Plattformen

Läuft die API als Serverless-Funktion, etwa auf Vercel, Netlify oder AWS Lambda, kommen eigene Fehlerquellen hinzu:

• Kaltstarts: Die erste Anfrage nach einer Pause dauert länger und läuft womöglich in ein Zeitlimit.
• Datenbankverbindungen: Jede Instanz öffnet eigene Verbindungen. Bei steigender Last kann das die Verbindungsgrenze der Datenbank sprengen. Ein Connection-Pooler hilft.
• Region: Liegen Funktion und Datenbank in verschiedenen Regionen, summieren sich Latenzen über mehrere Abfragen.
• Laufzeit-Umstellung: Hat der Anbieter die Standardversion von Node.js oder der Laufzeit geändert?

Den Fehler reproduzieren

Ist ein Verdacht gefunden, stellen Sie den Fehler gezielt nach, am besten in einer Staging-Umgebung oder lokal mit denselben Daten. Ein reproduzierbarer Fehler ist ein halb gelöster Fehler. Speichern Sie die auslösende Anfrage als curl-Befehl, damit Sie und andere sie nach der Korrektur erneut ausführen können.

Daraus entsteht im besten Fall ein automatischer Test, der genau diesen Fall abdeckt:

it("liefert 400 statt 500 bei fehlendem Lieferdatum", async () => {
  const res = await request(app)
    .post("/v1/bestellungen")
    .send({ id: 123 });
  expect(res.status).toBe(400);
});

Nach der Störung

Ist der Betrieb wiederhergestellt, lohnt sich eine kurze Nachbetrachtung, ohne Schuldfrage:

1. Ursache: Was genau ist passiert?
2. Erkennung: Wie und wann wurde der Fehler bemerkt, und hätte es früher gehen können?
3. Absicherung: Welcher Test, welche Validierung, welches Monitoring hätte ihn verhindert oder früher gemeldet?
4. Fehlerbehandlung: Liefert die API bei vorhersehbaren Problemen jetzt sinnvolle Statuscodes und Meldungen?

Typische Maßnahmen danach sind ein zentraler Error-Handler mit vollständigem Logging, Request-IDs in jeder Antwort, Timeouts und Wiederholungsversuche bei externen Aufrufen sowie eine Benachrichtigung, wenn die Fehlerrate steigt.

Ein Beispiel für einen zentralen Error-Handler in Express, der Fehler mit Request-ID protokolliert, dem Aufrufer aber keine internen Details verrät:

app.use((err, req, res, next) => {
  const requestId = req.headers["x-request-id"] ?? crypto.randomUUID();
  console.error({ requestId, path: req.path, err });
  res.status(500).json({
    fehler: "Interner Fehler",
    requestId,
  });
});

Mit der Request-ID in der Antwort kann ein Partner oder Kunde Ihnen genau sagen, welche Anfrage fehlgeschlagen ist, und Sie finden den passenden Logeintrag in Sekunden.

Wenn die Ursache unklar bleibt

Manche 500er treten nur sporadisch auf, nur unter Last oder nur bei einem Kunden. Dann ist eine strukturierte Analyse sinnvoller als weitere Vermutungen.

Häufige Fragen

Was ist der Unterschied zwischen HTTP 500, 502, 503 und 504?

Ein 500 bedeutet, dass Ihre Anwendung selbst einen Fehler geworfen hat. Bei 502 hat ein vorgeschalteter Proxy oder Load Balancer keine gültige Antwort von der Anwendung bekommen, bei 503 ist der Dienst überlastet, im Wartungsmodus oder nicht gestartet, und bei 504 hat die Anwendung zu lange gebraucht. Die Fehlersuche beginnt deshalb je nach Code an einer anderen Stelle.

Was sollte ich als Erstes tun, wenn die API plötzlich 500er liefert?

Klären Sie, ob alle Anfragen betroffen sind oder nur bestimmte, seit wann der Fehler auftritt und was zu diesem Zeitpunkt geändert wurde. Lag kurz vor dem ersten Fehler ein Deployment, ist ein Rollback auf die vorherige Version oft der schnellste Weg, den Betrieb wiederherzustellen. Die Ursache wird danach in Ruhe gesucht.

Ist ein 500er bei ungültigen Eingaben normal?

Nein, das ist selbst ein Fehler. Bei ungültigen Eingaben sollte die API einen 4xx-Code mit verständlicher Meldung liefern, etwa 400 bei einem fehlenden Pflichtfeld. Ein automatischer Test, der genau diesen Fall abdeckt, verhindert, dass der Fehler zurückkommt.

---

Bleibt die Ursache unklar, lohnt sich eine Fehlerdiagnose als eigene Aufgabe. Sie beschreiben den Fehler auf Ihrem Board, mit Zeitpunkt, Request-ID und der auslösenden Anfrage, und laden uns in Ihr Repository ein, statt Zugangsdaten zu verschicken. 48 Stunden nach Start erhalten Sie einen schriftlichen Befund mit Ursache, Belegen und betroffenen Stellen; gezählt wird von Montag 8 Uhr bis Freitag 16 Uhr. Die Behebung schlagen wir als nächste Karte vor, mit eigenen Abnahmekriterien und geliefert als Pull Request, nie direkt in Ihre Produktion. Die erste Aufgabe ist kostenlos, weitere arbeiten wir im Prozess-Abo in Ihrer Reihenfolge ab, und jede Lieferung prüft und gibt ein Senior-Entwickler frei. Typische Fehlerbehebungen mit Umfang und Abnahmekriterien zeigt der Leistungskatalog.