Beginnen Sie mit der tatsächlich fehlgeschlagenen Antwort
Halten Sie Methode, Pfad, Zeitpunkt, Anmeldezustand, Status, Inhaltstyp und eine gegebenenfalls vorhandene Korrelationskennung fest. Entfernen Sie Zugangsdaten und vertrauliche Inhalte aus weitergegebenen Belegen. Prüfen Sie, ob die Antwort von der Anwendung, einem Gateway oder einem vorgeschalteten Dienst stammt. Eine HTML-Fehlerseite vor einer JSON-API kann erklären, warum der Client das Ergebnis nicht lesen kann.
Bei Browsern kann ein CORS-Problem den Zugriff auf eine tatsächlich vorhandene Antwort verhindern. Ein Timeout lässt dagegen offen, ob die serverseitige Aktion bereits ausgeführt wurde. Wiederholen Sie eine schreibende Anfrage deshalb nicht blind; Retries und Idempotenz behandeln den unklaren Ausgang.
Statuscodes nach ihrer Bedeutung unterscheiden
Die folgende Auswahl hilft bei Sicherheits- und Datenvertragsfragen. Die normative Grundlage ist RFC 9110, Abschnitte 15.5 und 15.6. Sie ist keine Liste aller möglichen API-Fehler.
Bei schmaler Ansicht können Sie die Tabelle seitlich scrollen.
| Status | Bedeutung für die Einordnung | Sinnvoller nächster Schritt |
|---|---|---|
400 Bad Request | Die Anfrage wird wegen eines wahrgenommenen Clientfehlers nicht verarbeitet, etwa fehlerhafter Syntax | Format, Pflichtangaben und konkreten API-Vertrag prüfen |
401 Unauthorized | Für die Zielressource fehlen gültige Authentifizierungsdaten; der Server muss eine passende WWW-Authenticate-Challenge senden | Verwendeten Zugang, Tokenart und Gültigkeit prüfen; keine Geheimnisse ins Fehlerprotokoll kopieren |
403 Forbidden | Der Server versteht die Anfrage und verweigert sie; der Grund muss nicht mit Zugangsdaten zusammenhängen | Dokumentierten Fehlergrund und erforderliche Befugnis prüfen; gleiche Anfrage nicht unverändert automatisiert wiederholen |
404 Not Found | Keine aktuelle Darstellung gefunden oder deren Existenz wird nicht offengelegt | Pfad und vorgesehene Sichtbarkeit prüfen; keine sichere Aussage „Objekt existiert nicht“ ableiten |
405 Method Not Allowed | Die bekannte Methode wird für diese Ressource nicht unterstützt; die Antwort muss Allow enthalten | Methode mit dem konkreten Ressourcenvertrag abgleichen |
409 Conflict | Konflikt mit dem aktuellen Zustand der Ressource | Zustand neu prüfen und Konflikt fachlich lösen |
413 Content Too Large | Der Requestinhalt überschreitet die akzeptierte Größe | Umfang an dokumentierte Grenzen anpassen |
415 Unsupported Media Type | Das Inhaltsformat wird für diese Methode und Ressource nicht unterstützt | Tatsächlichen Inhalt, Content-Type und gegebenenfalls Content-Encoding abgleichen |
422 Unprocessable Content | Inhaltstyp verstanden und Syntax korrekt, enthaltene Anweisungen aber nicht verarbeitbar | Verständliche fachliche Fehlerdetails auswerten |
5xx | Ein Serverfehler verhindert die vorgesehene Bearbeitung | Geschützte Betriebsdiagnose nutzen; Wiederholung nur nach geeignetem Vertrag |
„401 heißt nicht angemeldet, 403 heißt angemeldet“ ist als allgemeine Regel zu eng: RFC 9110 erlaubt ausdrücklich Gründe für 403, die von Credentials unabhängig sind. Für OAuth-Bearer-Fehler kommen zusätzliche Regeln des verwendeten Protokollprofils hinzu. Ein 404 darf die Existenz einer verbotenen Ressource verbergen. Wählen Sie diese Sichtbarkeit bewusst und konsistent; auch Antwortinhalt und andere beobachtbare Unterschiede können Informationen verraten.
429 Too Many Requests gehört zur Begrenzung von Anfragen und ist in RFC 6585, Abschnitt 4 definiert. Ein optionales Retry-After hilft bei der Warteentscheidung, beweist aber keine wirksame Begrenzung aller Abläufe. Dazu führt Rate-Limits.
Problem Details vereinheitlichen den Fehlerkörper
Wenn Clients maschinenlesbare Zusatzinformationen benötigen, bietet RFC 9457 das Format Problem Details. Er ersetzt RFC 7807. Das Format ist eine mögliche gemeinsame Vereinbarung; nicht jede API muss deshalb ihren vorhandenen domänenspezifischen Fehlervertrag austauschen. RFC 9457, Abschnitte 1 und 4.
Das folgende synthetische Beispiel beschreibt eine fachlich unzulässige Datumsreihenfolge. Die Adresse unter .invalid ist ein ausdrücklich nicht erreichbares Beispiel; für eine reale API wäre eine stabile Problemtypkennung unter eigener Kontrolle zu wählen.
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Cache-Control: no-store
{
"type": "https://api.example.invalid/problems/invalid-date-range",
"title": "Ungültiger Zeitraum",
"status": 422,
"detail": "Das Enddatum muss am oder nach dem Startdatum liegen.",
"instance": "urn:uuid:17ce8990-26ec-4dad-a379-472107807b05",
"errors": [
{ "pointer": "/end_date", "code": "before_start" }
]
}
type identifiziert die Problemart, title benennt sie kurz, detail hilft beim konkreten Fall und instance bezeichnet dieses Vorkommnis. Der hier definierte errors-Eintrag ist eine eigene Erweiterung; seine Felder sind kein universeller Vertrag aller Problem-Details-APIs. Eine stabile Kennung eignet sich für Cliententscheidungen besser als das Auswerten eines übersetzten Erklärungssatzes.
Wenn der Erzeuger status mitsendet, muss er denselben Code im tatsächlichen HTTP-Status verwenden. Ein 200 mit "status": 422 im Body ist kein gleichwertiger Ersatz: Proxys, Caches und allgemeine HTTP-Clients arbeiten mit dem HTTP-Status. Das gezeigte no-store ist eine bewusste Cacheentscheidung für dieses Beispiel, keine pauschale RFC-Pflicht für alle Problemantworten. RFC 9457, Abschnitt 3.1.
Geben Sie Korrekturhilfe statt Debugdaten aus
Eine Validierungsantwort darf beispielsweise sagen, dass ein öffentliches Feld einen ungültigen Wert besitzt. Sie sollte keine SQL-Anweisung, internen Dateipfade, Stacktraces, Tokens oder kompletten Kundendatensätze enthalten. Auch ein Link auf eine detaillierte Fehlerinstanz braucht einen geeigneten Zugriffsschutz. Eine schwer erratbare Korrelationskennung ist für sich keine Berechtigung.
Interne Diagnose kann Ursachenklasse, betroffenen Dienst, sichere Metadaten und eine Kennung enthalten. Der Client erhält nur den für ihn vorgesehenen Ausschnitt. Begrenzen und bereinigen Sie auch die interne Aufzeichnung; ein geschütztes Log ist kein Grund, alle Geheimnisse und Requestbodies dauerhaft mitzuschreiben. RFC 9457, Abschnitt 5, OWASP Error Handling.
Ein globaler Fehlerhandler hilft bei unerwarteten Ausnahmen. Daneben brauchen die vorgesehenen Fehlerfälle verständliche Antworten. Prüfen Sie auch Parser, Anmeldung, Router, Proxy und nachgelagerte Dienste: Sie können scheitern, bevor Ihr Handler erreicht wird. CORS- und Inhaltstypregeln müssen im jeweils benötigten Antwortkontext ebenfalls konsistent bleiben.
Prüfen Sie Antwort und Nebenwirkung zusammen
Erzeugen Sie in einer isolierten Umgebung gezielt bekannte Fehler mit eigenen synthetischen Daten: fehlender Zugang, fehlendes Recht, ungültiger Zeitraum, unbekannter eigener Testpfad und kontrollierter Ausfall einer Testabhängigkeit. Vergleichen Sie Status, Header und Body mit dem vereinbarten Vertrag. Für eine unerwartete Ausnahme prüfen Sie, ob der Client einen begrenzten Fehler und der zuständige Betrieb einen korrelierbaren Diagnoseeintrag erhält.
Kontrollieren Sie bei abgelehnten Änderungen zusätzlich den Datenbestand und etwaige Jobs. Eine Fehlermeldung nach bereits erfolgter unerlaubter Speicherung ist kein erfolgreicher Berechtigungsnachweis. Behalten Sie bei einer Formatumstellung auch legitime ältere Clients im Blick. Eine sichere Rücknahme behält korrekte Statuscodes und die Begrenzung interner Details bei, selbst wenn sie zunächst zum vorherigen Fehlerformat zurückkehrt.
Was ein Fehlerbefund des API Security Check aussagt
Der öffentliche Check betrachtet einen begrenzten GET-Fehlerpfad und sucht in auswertbaren Antworten nach ausgewählten Mustern, etwa für Stacktraces, Datenbankfehler, interne Pfade oder Debughinweise. Bei 401 oder 403 wird diese Teilprüfung abgebrochen. Nicht vollständig oder nicht sinnvoll auswertbare Antworten müssen mit ihrer Messgrenze gelesen werden.
Ein Treffer ist ein Hinweis, den Sie an der konkreten Antwort einordnen sollten. Er beweist keine ausnutzbare Injection oder vollständige Kompromittierung. Ohne Treffer sind andere Fehlerpfade, angemeldete Abläufe und Schreiboperationen weiterhin ungeprüft. Der Check validiert auch keinen vollständigen Problem-Details-Vertrag.
Für Header, Allow und Bewertungsgrenzen führt HTTP-Befunde lesen weiter. Logging und Monitoring erklärt die betriebliche Seite; API-Sicherheit selbst prüfen verbindet Fehlerverhalten und fachliche Schutzregeln.
Quellen und Stand
Quellenstand: 27. September 2026. Die Links stehen zusätzlich bei den jeweils begründeten Aussagen.