Blog

HTTP Statuscodes für REST APIs: Die Richtige Wahl

Ashley Innocent

Ashley Innocent

13 March 2026

HTTP Statuscodes für REST APIs: Die Richtige Wahl

Apidog für Unternehmen

On-Premises Bereitstellung

SSO & RBAC

SOC 2 konform

Apidog Enterprise entdecken

TL;DR

REST-APIs sollten HTTP-Statuscodes korrekt verwenden: 200 für erfolgreiche GET-Anfragen, 201 für erfolgreiche POST-Anfragen mit Ressourcenerstellung, 204 für erfolgreiche DELETE-Anfragen, 400 für Client-Fehler, 401 für Authentifizierungsfehler, 404 für nicht gefunden und 500 für Server-Fehler. Die moderne PetstoreAPI implementiert alle standardmäßigen HTTP-Statuscodes mit korrekter Semantik und RFC 9457-Fehlerantworten.

Einleitung

Ihre API gibt für alles 200 OK zurück. Erfolg? 200 OK. Validierungsfehler? 200 OK mit einer Fehlermeldung im Body. Ressource nicht gefunden? 200 OK mit {"error": "nicht gefunden"}. Authentifizierungsfehler? Sie haben es erraten – 200 OK.

Das ist falsch. HTTP-Statuscodes existieren aus einem Grund. Sie informieren Clients darüber, was passiert ist, ohne den Antwort-Body parsen zu müssen. Caches, Proxys und Überwachungstools verlassen sich auf Statuscodes. Wenn Sie 200 für Fehler zurückgeben, stören Sie das gesamte HTTP-Ökosystem.

Der alte Swagger Petstore machte Fehler bei Statuscodes: Rückgabe von 200 für POST-Anfragen, die 201 zurückgeben sollten, Verwendung von 200 für DELETE-Operationen, die 204 zurückgeben sollten, und fehlende wichtige Fehlercodes. Modern PetstoreAPI behebt dies, indem es an allen Endpunkten eine korrekte HTTP-Semantik implementiert.

💡
Wenn Sie REST-APIs entwickeln oder testen, hilft Ihnen Apidog, die Verwendung von Statuscodes zu validieren, Fehlerszenarien zu testen und sicherzustellen, dass Ihre API den HTTP-Standards entspricht. Sie können erwartete Statuscodes definieren, automatisierte Tests durchführen und fehlerhafte Antworten vor der Bereitstellung abfangen.
Button

In diesem Leitfaden erfahren Sie, welche HTTP-Statuscodes für REST-APIs wichtig sind, wann sie jeweils zu verwenden sind und wie Modern PetstoreAPI sie korrekt implementiert.

Das Statuscode-Problem

Viele APIs betrachten Statuscodes als Nebensächlichkeit. Das Ergebnis: kaputte HTTP-Semantik und verwirrte Clients.

Das Anti-Pattern „Überall 200 OK“

// Erfolg
GET /users/123
200 OK
{"id": 123, "name": "John"}

// Fehler (aber immer noch 200!)
GET /users/999
200 OK
{"error": "Benutzer nicht gefunden"}

// Validierungsfehler (immer noch 200!)
POST /users
200 OK
{"error": "E-Mail ist erforderlich"}

Probleme:

Warum das passiert

Entwickler geben 200 zurück, weil:

  1. Sie die anderen Statuscodes nicht kennen
  2. Sie denken, Statuscodes seien optional
  3. Sie vermeiden wollen, Clients zu „brechen“
  4. Sie schlechte Beispiele kopieren (wie den alten Swagger Petstore)

Essentielle HTTP-Statuscodes für REST-APIs

Sie benötigen nicht alle über 60 HTTP-Statuscodes. Konzentrieren Sie sich auf diese essentiellen.

Kurzübersicht

Erfolg (2xx):

Client-Fehler (4xx):

Server-Fehler (5xx):

Erfolgscodes (2xx)

Erfolgscodes zeigen an, dass die Anfrage erfolgreich war. Verschiedene Codes vermitteln unterschiedliche Bedeutungen.

200 OK

Verwendung für: Erfolgreiche GET-, PUT-, PATCH-Anfragen, die Daten zurückgeben.

GET /pets/123
200 OK
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "KATZE"
}

Nicht verwenden für: POST-Anfragen, die Ressourcen erstellen (verwenden Sie 201), DELETE-Anfragen (verwenden Sie 204).

201 Created

Verwendung für: Erfolgreiche POST-Anfragen, die eine neue Ressource erstellen.

POST /pets
201 Created
Location: https://petstoreapi.com/pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "KATZE"
}

Wichtige Punkte:

Modern PetstoreAPI gibt 201 für alle POST-Operationen zurück, die Ressourcen erstellen.

204 No Content

Verwendung für: Erfolgreiche DELETE-, PUT- oder PATCH-Anfragen ohne Antwort-Body.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
204 No Content

Wichtige Punkte:

Client-Fehlercodes (4xx)

Client-Fehlercodes zeigen an, dass der Client einen Fehler gemacht hat. Die Anfrage sollte ohne Modifikation nicht wiederholt werden.

400 Bad Request

Verwendung für: Fehlgeformte Anfragen, ungültiges JSON, fehlende Pflichtfelder.

POST /pets
400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validierungsfehler",
  "status": 400,
  "detail": "Anfragevalidierung fehlgeschlagen",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Name ist erforderlich"
    }
  ]
}

Modern PetstoreAPI verwendet das RFC 9457-Format für alle Fehlerantworten.

401 Unauthorized

Verwendung für: Fehlende oder ungültige Authentifizierungsdaten.

GET /pets
401 Unauthorized
WWW-Authenticate: Bearer realm="PetstoreAPI"

{
  "type": "https://petstoreapi.com/errors/authentication-required",
  "title": "Authentifizierung erforderlich",
  "status": 401,
  "detail": "Gültige Authentifizierungsdaten erforderlich"
}

Wichtige Punkte:

403 Forbidden

Verwendung für: Authentifizierter Benutzer hat keine Berechtigung.

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
403 Forbidden

{
  "type": "https://petstoreapi.com/errors/insufficient-permissions",
  "title": "Unzureichende Berechtigungen",
  "status": 403,
  "detail": "Sie haben keine Berechtigung, dieses Haustier zu löschen"
}

Unterschied zu 401:

404 Not Found

Verwendung für: Ressource existiert nicht.

GET /pets/nonexistent-id
404 Not Found

{
  "type": "https://petstoreapi.com/errors/not-found",
  "title": "Nicht gefunden",
  "status": 404,
  "detail": "Haustier nicht gefunden"
}

Nicht verwenden für: Autorisierungsfehler (verwenden Sie 403), Validierungsfehler (verwenden Sie 400).

409 Conflict

Verwendung für: Ressourcenkonflikte wie Duplikate oder Versionskonflikte.

POST /pets
409 Conflict

{
  "type": "https://petstoreapi.com/errors/duplicate-resource",
  "title": "Ressource dupliziert",
  "status": 409,
  "detail": "Ein Haustier mit dieser Mikrochip-ID existiert bereits"
}

422 Unprocessable Entity

Verwendung für: Gültiges Anfrageformat, aber semantische Fehler.

POST /pets
422 Unprocessable Entity

{
  "type": "https://petstoreapi.com/errors/business-rule-violation",
  "title": "Verstoß gegen Geschäftsregel",
  "status": 422,
  "detail": "Es dürfen nicht mehr als 5 Haustiere pro Haushalt adoptiert werden"
}

Unterschied zu 400:

429 Too Many Requests

Verwendung für: Ratenlimit überschritten.

GET /pets
429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1678886400

{
  "type": "https://petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Ratenlimit überschritten",
  "status": 429,
  "detail": "Das Ratenlimit von 100 Anfragen pro Stunde wurde überschritten"
}

Modern PetstoreAPI verwendet IETF Ratenlimit-Header.

Server-Fehlercodes (5xx)

Server-Fehlercodes zeigen an, dass der Server einen Fehler hatte. Clients können diese Anfragen wiederholen.

500 Internal Server Error

Verwendung für: Unerwartete Serverfehler.

GET /pets
500 Internal Server Error

{
  "type": "https://petstoreapi.com/errors/internal-error",
  "title": "Interner Serverfehler",
  "status": 500,
  "detail": "Ein unerwarteter Fehler ist aufgetreten"
}

Nicht einschließen: Stack-Traces, interne Details, Datenbankfehler in der Produktion.

503 Service Unavailable

Verwendung für: Temporäre Nichtverfügbarkeit (Wartung, Überlastung).

GET /pets
503 Service Unavailable
Retry-After: 3600

{
  "type": "https://petstoreapi.com/errors/service-unavailable",
  "title": "Dienst nicht verfügbar",
  "status": 503,
  "detail": "Dienst aufgrund von Wartungsarbeiten vorübergehend nicht verfügbar"
}

Den Retry-After-Header einschließen, um Clients mitzuteilen, wann sie es erneut versuchen können.

Wie Modern PetstoreAPI Statuscodes verwendet

Modern PetstoreAPI implementiert an allen Endpunkten eine korrekte HTTP-Semantik.

Beispiel: Haustierverwaltung

// Haustiere auflisten
GET /pets
200 OK

// Haustier erstellen
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

// Haustier abrufen
GET /pets/{id}
200 OK (gefunden) oder 404 Nicht gefunden

// Haustier aktualisieren
PUT /pets/{id}
200 OK (mit Body) oder 204 No Content

// Haustier löschen
DELETE /pets/{id}
204 No Content (erfolgreich) oder 404 Nicht gefunden

Fehlerantworten

Alle Fehler verwenden das RFC 9457-Format:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validierungsfehler",
  "status": 400,
  "detail": "Anfragevalidierung fehlgeschlagen",
  "instance": "/pets",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Name muss zwischen 1 und 100 Zeichen lang sein"
    }
  ]
}

Siehe die Fehlerbehandlungsdokumentation der Modern PetstoreAPI für vollständige Beispiele.

Testen von Statuscodes mit Apidog

Apidog hilft Ihnen, das Verhalten von Statuscodes in allen Szenarien zu testen.

Erwartete Statuscodes definieren

paths:
  /pets:
    post:
      responses:
        '201':
          description: Haustier erstellt
        '400':
          description: Validierungsfehler
        '401':
          description: Authentifizierung erforderlich
        '429':
          description: Ratenlimit überschritten

Alle Szenarien testen

Erstellen Sie Testfälle für:

Automatisierte Tests

// Apidog Testskript
pm.test("Gibt 201 für erfolgreiche Erstellung zurück", () => {
  pm.response.to.have.status(201);
  pm.response.to.have.header("Location");
});

pm.test("Gibt 400 für fehlende Pflichtfelder zurück", () => {
  pm.response.to.have.status(400);
  pm.expect(pm.response.json().type).to.include("validation-error");
});

Häufige Fehler, die es zu vermeiden gilt

Fehler 1: Verwendung von 200 für POST

// Falsch
POST /pets
200 OK

// Korrekt
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

Fehler 2: Verwendung von 200 für DELETE

// Falsch
DELETE /pets/{id}
200 OK
{"message": "Erfolgreich gelöscht"}

// Korrekt
DELETE /pets/{id}
204 No Content

Fehler 3: Verwechslung von 401 und 403

// Falsch: Benutzer ist authentifiziert, hat aber keine Berechtigung
401 Unauthorized

// Korrekt
403 Forbidden

Fehler 4: Verwendung von 500 für Client-Fehler

// Falsch: Validierungsfehler gibt 500 zurück
POST /pets
500 Internal Server Error

// Korrekt
POST /pets
400 Bad Request

Fazit

HTTP-Statuscodes sind nicht optional. Sie sind Teil der HTTP-Spezifikation und essentiell für den Aufbau korrekter REST-APIs.

Verwenden Sie die richtigen Statuscodes:

Modern PetstoreAPI demonstriert die korrekte Verwendung von Statuscodes an allen Endpunkten. Studieren Sie die REST API-Dokumentation, um die korrekte Implementierung zu sehen.

Testen Sie Ihre Statuscodes mit Apidog, um sicherzustellen, dass Ihre API den HTTP-Standards entspricht.

FAQ

Soll ich 200 oder 204 für einen erfolgreichen DELETE verwenden?

Verwenden Sie 204 No Content. Dies zeigt Erfolg ohne Antwort-Body an und spart Bandbreite. Verwenden Sie 200 nur, wenn Sie Informationen über die gelöschte Ressource zurückgeben müssen.

Was ist der Unterschied zwischen 400 und 422?

400 bedeutet, dass die Anfrage fehlerhaft ist (ungültiges JSON, falsche Typen). 422 bedeutet, dass die Anfrage wohlgeformt ist, aber Geschäftsregeln verletzt.

Wann sollte ich 401 gegenüber 403 verwenden?

401 bedeutet „authentifizieren Sie sich“ (fehlende oder ungültige Anmeldeinformationen). 403 bedeutet „Sie sind authentifiziert, aber nicht autorisiert“ (unzureichende Berechtigungen).

Soll ich 404 oder 403 für Ressourcen zurückgeben, auf die Benutzer nicht zugreifen können?

Geben Sie 403 zurück, wenn die Ressource existiert, der Benutzer aber keine Berechtigung hat. Geben Sie 404 zurück, wenn Sie die Existenz der Ressource vor unbefugten Benutzern verbergen möchten.

Wie teste ich alle Statuscode-Szenarien?

Verwenden Sie Apidog, um Testfälle für Erfolge, Validierungsfehler, Authentifizierungsfehler, nicht gefundene Ressourcen und Serverfehler zu erstellen. Führen Sie automatisierte Tests in CI/CD durch.

Welcher Statuscode für Ratenbegrenzung?

Verwenden Sie 429 Too Many Requests mit RateLimit-*-Headern. Fügen Sie Retry-After hinzu, um Clients mitzuteilen, wann sie es erneut versuchen können.

Soll ich 500 für alle Serverfehler verwenden?

Verwenden Sie 500 für unerwartete Fehler. Verwenden Sie 502 für Fehler im Upstream-Dienst, 503 für temporäre Nichtverfügbarkeit und 504 für Timeouts.

Wie handhabt Modern PetstoreAPI Fehler?

Alle Fehler verwenden das RFC 9457-Format mit korrekten Statuscodes. Siehe die Fehlerbehandlungsdokumentation für Beispiele.

Praktizieren Sie API Design-First in Apidog

Entdecken Sie eine einfachere Möglichkeit, APIs zu erstellen und zu nutzen

Kostenlos registrierenHerunterladen