API-Antworten und Fehler verstehen

Wie eine Antwort der API aufgebaut ist, woran du einen Fehler erkennst und was die einzelnen Fehlertypen bedeuten. Mit diesem Wissen baust du deine Integration robust und findest Probleme schnell.

Aufbau erfolgreicher Antworten
Die sechs Fehlertypen und ihre Statuscodes
Fehler-Header und die trace_id für den Support

Erfolgreiche Antworten

Nutzdaten liegen immer unter data. Eine einzelne Ressource steht als Objekt darin, eine Liste als Array.

{
  "data": {
    "id": 10001,
    "label": "mein-webserver",
    "status": "Active"
  }
}

Bei manchen Routen kommen zusätzliche Felder wie meta (etwa für Paginierung) oder message (ein erklärender Hinweis) dazu. Der data-Umschlag bleibt aber die Konstante, an der du dich orientierst.

Woran du einen Fehler erkennst

Fehler kommen ohne data-Umschlag. Stattdessen steht das Fehlerobjekt direkt auf oberster Ebene und beginnt immer mit error: true. Drei Felder sind bei jedem Fehler dabei:

error: immer true.
trace_id: eine eindeutige Kennung für genau diesen Fehler.
type: der Fehlertyp, siehe unten.
message: eine kurze, menschenlesbare Beschreibung.

Je nach Fehlertyp kommen weitere Felder hinzu. Beim fehlenden Bestätigungstoken sieht das zum Beispiel so aus:

{
  "error": true,
  "trace_id": "67d82f94-7a6f-40fe-a49f-6a10d888a52f",
  "type": "confirmation_error",
  "message": "Confirmation token not found by value.",
  "required_type": "reinstall_os",
  "required_id": "10001",
  "hint_route": "https://api.pph.systems/api/confirmation-token?for=reinstall_os&related_id=10001"
}

Werte deine Fehlerbehandlung immer über das Feld type aus, nicht über den Text in message. Der Typ ist stabil, die Formulierung der Nachricht kann sich ändern.

Die Fehlertypen im Überblick

Es gibt sechs Fehlertypen. Der HTTP-Statuscode dazu ist in der Regel wie folgt.

type	Status	Bedeutung	Was du tun kannst
`authentication_error`	401	Token fehlt, ist falsch oder wurde widerrufen	Token prüfen und korrekt im `Authorization`-Header senden
`access_denied`	403	Der Token darf diese Route nicht nutzen	Berechtigungen des Tokens prüfen, Gated Routes freigeben
`entity_not_found`	404	Die angefragte Ressource existiert nicht oder gehört dir nicht	ID prüfen
`validation_error`	422	Die Anfrage ist unvollständig oder ungültig	Fehlende oder falsche Parameter korrigieren
`confirmation_error`	400	Für eine kritische Aktion fehlt das Bestätigungstoken	Token erzeugen und im `X-Confirmation-Token`-Header senden
`general_error`	500	Ein unerwarteter Fehler auf unserer Seite	Später erneut versuchen, bei anhaltendem Fehler die `trace_id` an den Support geben

Zwei Beispiele, die dir am Anfang oft begegnen. Bei einer Route, die dein Token nicht nutzen darf:

{
  "error": true,
  "trace_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "type": "access_denied",
  "message": "Access to the route vps.status.reboot is denied."
}

Bei einer unvollständigen Anfrage:

{
  "error": true,
  "trace_id": "3f7c1e02-6a44-4c9a-8f1e-9b2d5c7a0e11",
  "type": "validation_error",
  "message": "The given data was invalid."
}

Fehler stehen auch in den Headern

Zusätzlich zum Body liefert jede Fehlerantwort drei Header. Praktisch, wenn du in einem Skript nur die Header prüfen willst, ohne den Body zu parsen.

X-Error-Type
X-Error-Message
X-Error-Trace-Id

Das maßgebliche Feld für deine Logik bleibt type im Body.

Rate-Limit

Jeder Token hat ein Anfragekontingent pro Zeitfenster. Zwei Header zeigen dir bei jeder Antwort deinen Stand:

X-RateLimit-Limit: dein Kontingent im aktuellen Fenster.
X-RateLimit-Remaining: wie viele Anfragen dir noch bleiben.

Ist das Kontingent aufgebraucht, antwortet die API mit HTTP 429. Warte in dem Fall kurz und wiederhole die Anfrage. Baue in automatisierten Abläufen am besten ein, dass X-RateLimit-Remaining beobachtet wird, bevor es so weit kommt. Mehr dazu steht in Wie ist die API abgesichert?.

Die trace_id ist dein Draht zum Support

Jede Fehlermeldung enthält eine trace_id. Wir protokollieren Fehler serverseitig, und diese Kennung verbindet deine Fehlermeldung mit unserem Protokoll. Wenn du dich mit einem Problem an uns wendest, gib die trace_id mit an. So finden unsere Entwickler den Vorgang sofort, ohne raten zu müssen.

Wie geht es weiter?

Wie du deine erste Anfrage stellst, steht im Quickstart.
Wie du kritische Aktionen freigibst, steht in Kritische Aktionen mit einem Bestätigungstoken freigeben.

Noch Fragen?

Technische Fragen zur API beantworten dir unsere Entwickler direkt in unserem Discord. Stell deine Frage im Entwickler-Channel und pinge das Dev-Team an.