API-Umstellung: Fehlerbehandlung

Die neue API (https://llm-server.ai.t-systems.net/v1) führt strukturierte Fehlerantworten ein. Damit können Anwendungen Fehler leichter erkennen und einheitlich behandeln. Standard-HTTP-Statuscodes zeigen weiterhin das Ergebnis einer Anfrage an, für bestimmte Fehlerfälle gibt es nun genauere Statuscodes. Die allgemeine Fehlerreferenz finden Sie unter Fehlercodes.

Was ändert sich?

Szenario	Legacy-API	Neue API
Fehlender API-Schlüssel	403	401
Ungültiger API-Schlüssel	401	401
Gesperrter oder deaktivierter Schlüssel	401	403
Modell nicht gefunden	404	400 bei Fehlern der Modellauflösung
Zugriff auf das Modell verweigert	404	403
Rate-Limit überschritten	429	429
Budget überschritten	429	402
Ungültige Anfrage	400, manchmal als Klartext	400, strukturiertes JSON
Verbindungsfehler zum Provider	500	502
Timeout beim Provider	500	504

Beispiel: Fehlerantwort

Die Legacy-API liefert Fehlerinformationen des Providers in der Regel als String in detail. Die neue API liefert strukturierte Fehlerinformationen.

Legacy-API (HTTP 400)

{
  "detail": "Error: 400 - Bad Request - {\"error\":{\"message\":\"Invalid request parameter\",\"type\":\"invalid_request_error\"}}"
}

Neue API (HTTP 400)

{
  "error": {
    "message": "Invalid request parameter",
    "type": "invalid_request_error",
    "code": "invalid_value",
    "param": "messages[0].role"
  }
}

Hinweis

Diese Beispiele sind vereinfacht und zeigen den Unterschied in der Fehlerstruktur.

Mit strukturierten Fehlerfeldern greifen Anwendungen auf Fehlerdetails zu, ohne eine eingebettete Fehlermeldung des Providers auswerten zu müssen.

Was Sie prüfen sollten

Für die übliche Behandlung von HTTP-Fehlern: Anwendungen können sich weiterhin auf die HTTP-Statuscodes der Antwort verlassen.

Für eigene Fehlerbehandlung: Prüfen Sie Code, der von bestimmten Statuscodes, dem Text von Fehlermeldungen oder dem Feld detail der Legacy-API abhängt.

Verwenden Sie den tatsächlichen HTTP-Status der Antwort als wichtigsten Hinweis und behandeln Sie Fehlerfelder wie type, code und param als optional.

Rate-Limits und Wiederholungen

Die neue API unterscheidet zwischen Rate-Limits des Providers, Rate-Limits des Service und Budgetbeschränkungen.

Szenario	HTTP-Status	Informationen zur Wiederholung
Rate-Limit des Providers	429	Vom Provider gelieferte Informationen zur Wiederholung können verfügbar sein
Rate-Limit des Service	429	Kein Retry-After-Header; Informationen zum Zurücksetzen können in der Fehlermeldung stehen
Budget überschritten	402	Kein Retry-After-Header; Informationen zum Budget können in der Fehlermeldung stehen

Wenn ein Provider einen Retry-After-Header liefert und dieser in der Antwort weitergegeben wird, sollten Anwendungen ihn beachten. Bei Rate-Limits des Service verwenden Sie eine eigene Backoff-Strategie; siehe Rate-Limits.

Fehler zum Budget sollten gesondert behandelt werden und keine automatischen Wiederholungen auslösen.

Antwortvalidierung

Prüfen Sie den Content-Type der Antwort, bevor Sie den Body auswerten. Einige nicht unterstützte API-Pfade oder Methoden können HTML statt JSON zurückgeben.

Ein erfolgreicher HTTP-Status allein garantiert nicht, dass die Antwort die erwartete API-Struktur enthält.

Fehlersuche

Wenn Sie ein Problem melden, geben Sie den Zeitpunkt der Anfrage, den Endpunkt, den HTTP-Status und eine verfügbare Request- oder Trace-ID an. So kann der Support Anfragen schneller untersuchen.

Bei Fragen oder für Unterstützung bei der Migration erreichen Sie uns unter AI@t-systems.com.