Benutzung

Fehler

Standard-HTTP-Statuscodes, ein maschinenlesbarer Code im Body, nie Inhalte. Zwei Formate — weil die Inferenz-API das OpenAI-Format spricht, das jedes SDK versteht.

Zwei Formate

Welche Fläche antwortet, erkennst du am Pfad: OpenAI-Endpunkte antworten im OpenAI-Fehlerformat, die App-API mit unserem Envelope.

Inferenz-API (OpenAI-Format)

{
  "error": {
    "message": "Budget has been exceeded! Current cost: 14.02, Max budget: 14.0",
    "type": "budget_exceeded",
    "code": "429"
  }
}

Das Format, das die offiziellen OpenAI-SDKs als Exception abbilden — type und code kommen vom Gateway.

App-API (Envelope)

{
  "error": {
    "code": "scope_missing",
    "message": "This API key does not carry the scope this endpoint requires.",
    "request_id": "3f6c1c9e-0a4b-4c3e-9b0e-6a1d2f8e4b21"
  }
}

Ein festes Format mit request_id für jede Antwort — nenne sie im Support, wir finden die Anfrage ohne ihren Inhalt.

Fehlercodes

Status	Code	Fläche	Bedeutung
401	unauthorized	beide	Kein, ungültiger oder widerrufener API-Key.
401	key_expired	App-API	Der Key ist abgelaufen — neuen Key anlegen.
400	invalid_request_error	Inferenz	Anfrage ungültig (fehlende Pflichtfelder, unbekannter Parameter, Body zu groß).
400	invalid_body	App-API	Der Request-Body entspricht nicht dem Schema des Endpunkts.
403	scope_missing	App-API	Der Key trägt nicht den Scope, den dieser Endpunkt verlangt.
403	browser_request_rejected	App-API	Die Anfrage sieht wie ein Browser aus (Origin, Fetch-Metadaten oder Session-Cookie).
403	academy_only	App-API	Dieses Konto hat nur Zugang zur Akademie, nicht zur Plattform.
404	model_not_found	Inferenz	Unbekannte Modell-ID oder ein Modell, das dieser Key nicht ansprechen darf.
404	not_found	App-API	Die Ressource existiert nicht oder ist für diesen Key nicht freigegeben — beides antwortet 404.
429	rate_limit_error	beide	Zu viele Anfragen im Zeitfenster; retry-after nennt die Wartezeit.
429	budget_exceeded	beide	Das Nutzungskontingent der Organisation ist aufgebraucht — kein Retry hilft, bis das Fenster zurückgesetzt ist.
500	internal_error	beide	Interner Fehler; wiederholen und bei Wiederholung die request_id an den Support geben.
503	service_unavailable	Inferenz	Das Modell ist vorübergehend nicht erreichbar — mit Backoff wiederholen.

Umgang mit Fehlern

429 und 503 mit exponentiellem Backoff wiederholen; retry-after ist die Untergrenze.
budget_exceeded ist ebenfalls 429, aber kein Wiederholungsfall: Das Kontingent setzt sich mit dem Fenster zurück, nicht durch Warten von Sekunden.
Ein 404 unterscheidet nicht zwischen „gibt es nicht“ und „nicht für dich freigegeben“ — absichtlich, damit die API keine Existenz fremder Ressourcen verrät.
Die request_id der App-API identifiziert die Anfrage ohne ihren Inhalt; Logs auf unserer Seite enthalten nie Prompts oder Antworten.