Fehler, Limits, Retries

Fehlerformat

Fehler kommen im OpenAI-Format:

{
  "error": {
    "message": "No API key provided",
    "type": "invalid_api_key",
    "param": "api_key",
    "code": "401"
  }
}

Werte das Feld type aus, nicht den Text in message; die Texte können sich ändern.

Statuscodes

Status	type	Bedeutung	Was tun?
400	invalid_request_error	Request ungültig, z. B. unbekannter Modellname oder kein model angegeben.	Request korrigieren, Modellnamen in der Modellliste prüfen.
401	invalid_api_key	Key fehlt oder ist ungültig bzw. widerrufen.	Header Authorization: Bearer <key> prüfen.
402	payment_required	Guthaben leer. Privatkonto: mit Link zur Aufladung in der Console. Team-Mitglied: „ask your admin“.	Guthaben aufladen bzw. Admin fragen.
403	account_suspended	Konto gesperrt.	Support kontaktieren.
403	company_plan_paused	Der Team-Plan der Firma ist pausiert (gilt für Mitglieder).	Team-Owner fragen.
403	permission_denied	Modell für deine Firma nicht freigegeben, oder Partner-Modell ohne bisherige Aufladung.	Admin um Freigabe bitten bzw. aufladen.
403	model_not_enabled	Modell für dein Konto nicht freigeschaltet.	Open Hippo kontaktieren.
404	not_found_error	Pfad gibt es nicht.	Pfad mit der Endpunktliste abgleichen.
429	quota_exceeded	Ein Budget ist erreicht: Key, Konto, Mitglied oder Firma. Header Retry-After: 60.	Siehe Budgets & Limits.
429	rate_limit_exceeded	Nur bei GET /v1/usage: mehr als 30 Abfragen pro Minute und Key.	Nach Retry-After erneut abfragen.
503	service_unavailable	Authentifizierungsdienst vorübergehend nicht erreichbar. Header Retry-After: 60.	Nach Retry-After erneut versuchen.

Ein Pfad, den es gar nicht gibt, kann auch eine einfache 404-Antwort ohne JSON liefern.

Beispiele

Formatbeispiele mit den Meldungstexten des Gateways. Werte das Feld type aus; die Texte in message können sich ändern.

429, Budget des Keys mit hartem Stopp erreicht:

HTTP/2 429
Retry-After: 60
Content-Type: application/json

{
  "error": {
    "message": "API key spend limit reached",
    "type": "quota_exceeded",
    "param": "api_key",
    "code": "429"
  }
}

Andere Budgets liefern denselben type mit anderem Text, z. B. Monthly account budget reached (Konto), You have reached your monthly limit — ask your admin to raise it. (Mitglied) oder Your company has reached its monthly limit. (Firma).

402, Guthaben leer, Privatkonto:

{
  "error": {
    "message": "Insufficient credit balance. Top up at https://console.openhippo.io/billing",
    "type": "payment_required",
    "param": "api_key",
    "code": "402"
  }
}

402, Guthaben leer, Team-Mitglied:

{
  "error": {
    "message": "Your company's balance is empty — ask your admin to top up.",
    "type": "payment_required",
    "param": "api_key",
    "code": "402"
  }
}

Prüfreihenfolge

Vor jedem Request prüft die API in dieser Reihenfolge; der erste Treffer bestimmt den Fehler:

1. Konto gesperrt → 403 account_suspended
2. Team-Plan pausiert → 403 company_plan_paused
3. Guthaben bei 0 € → 402 payment_required
4. Budget des Keys erreicht → 429 quota_exceeded
5. Budget der Firma erreicht → 429 quota_exceeded
6. Budget des Mitglieds bzw. Kontos erreicht → 429 quota_exceeded

Das Ergebnis der Prüfung wird bis zu 60 Sekunden zwischengespeichert. Ein Budget kann deshalb knapp überschritten werden, bevor die Sperre greift.

Rate Limits

Feste RPM/TPM-Limits (Requests bzw. Tokens pro Minute) sind derzeit nicht dokumentiert. Für Lastplanung: support@openhippo.io. Ausnahme: GET /v1/usage erlaubt 30 Abfragen pro Minute und Key. Die 429 quota_exceeded oben sind Budgets, keine Rate Limits.

Retries

• Wiederholen lohnt sich bei 503: Warte so lange, wie Retry-After angibt.
• 429 quota_exceeded ist ein Budget, kein kurzfristiges Rate-Limit. Ein Retry hilft erst, wenn das Budget erhöht wird oder der neue Monat beginnt.
• Nicht wiederholen bei 400, 401, 402, 403 und 404: Der Request scheitert sonst genauso.

import os, time
import openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.openhippo.io/v1",
    api_key=os.environ["OPENHIPPO_API_KEY"],
    max_retries=0,  # control retries yourself
)

def chat(messages, attempts=3):
    for attempt in range(attempts):
        try:
            return client.chat.completions.create(model="openhippo/gpt-oss-120b", messages=messages)
        except openai.APIStatusError as e:
            if e.status_code != 503 or attempt == attempts - 1:
                raise
            time.sleep(int(e.response.headers.get("retry-after", "60")))

print(chat([{"role": "user", "content": "Hello!"}]).choices[0].message.content)