Fehler

Jede Nicht-2xx-Antwort hat dasselbe JSON-Format – den OpenAI-Standard. Verwenden Sie error.code für die programmatische Verarbeitung und status_code für die Wiederholungsrichtlinie.

Fehlernutzdaten

{
  "error": {
    "message": "Model 'xyz-2025' is not available",
    "type": "model_not_found",
    "code": "model_not_found",
    "param": null
  }
}

HTTP-Statuscodes

Häufige Fehlercodes

authentication_error

• Header Authorization: Bearer ... wurde nicht gesetzt.
• API-Schlüssel wurde unter /app/keys widerrufen.
• Der Schlüssel hat weiterhin das falsche Präfix (muss mit sk-kn- beginnen).

insufficient_quota

• Wallet-Guthaben für diese Anfrage zu niedrig → error.code ist insufficient_balance, und der Fehler enthält den Wallet-Kontostand (balance_usd), den für diese Anfrage reservierten Betrag (needed_usd) und zwei Links: topup_url öffnet die Abrechnungsseite mit vorausgewähltem Aufladebetrag, auto_recharge_url öffnet die Seite mit den Einstellungen für die automatische Aufladung. Keiner der Links löst selbst eine Zahlung aus.
• Monatliches Limit pro Schlüssel erreicht. Zurückgesetzt wird es zu Beginn des Kalendermonats (UTC). Erhöhen Sie das Limit unter /app/keys.

{
  "error": {
    "message": "Wallet balance is too low for this request. Top up at https://kunavo.com/app/billing — or turn on auto-recharge there, and a saved card refills the wallet before requests are refused.",
    "type": "insufficient_quota",
    "code": "insufficient_balance",
    "param": null,
    "balance_usd": 0.0142,
    "needed_usd": 0.0381,
    "topup_url": "https://kunavo.com/app/billing?topup=20",
    "auto_recharge_url": "https://kunavo.com/app/billing?autorecharge=1&src=api_402"
  }
}

Versuchen Sie es bei insufficient_balance nicht erneut, es sei denn, die Antwort enthält einen Retry-After-Header — dieser bedeutet, dass gerade eine automatische Abbuchung von Ihrer gespeicherten Karte läuft und dieselbe Anfrage wenige Sekunden später erfolgreich sein sollte.

permission_error

• Für den Schlüssel gilt eine IP-Zulassungsliste, und Ihr Aufruf kam von einer nicht darin enthaltenen Adresse. Die Meldung nennt die erkannte Adresse — fügen Sie sie (oder ihren CIDR-Block) unter /app/keys hinzu oder entfernen Sie die Zulassungsliste vollständig, um alle Adressen zuzulassen.
• Wenn Sie einen Agenten auf einen neuen Host oder ein neues NAT-Gateway verschieben oder einen Laptop in einem anderen Netzwerk verwenden, ändert sich diese Adresse. Ein Schlüssel ohne Zulassungsliste wird auf diese Weise niemals abgewiesen.

model_not_found

• Falsch geschriebener Slug. Verwenden Sie /models für die verbindliche Liste.
• Das Modell ist derzeit deaktiviert (Ausfall beim Upstream oder Überprüfung der Preise).

upstream_error

Gibt an, dass ein Upstream-Modellanbieter einen Fehler zurückgegeben hat, den wir keinem spezifischeren Code zuordnen konnten. Der Antworttext enthält die ursprüngliche Meldung. Häufige Ursachen:

• Überlastung auf Anbieterseite.
• Ablehnung durch die Inhaltsmoderation (versuchen Sie es mit einem anderen Prompt).
• Beschränkung nach Region oder Verfügbarkeit.

Strategie für erneute Versuche

Das einfachste robuste Muster: exponentielles Backoff mit Jitter, ausschließlich bei 429- und 5xx-Fehlern.

import time, random
from openai import OpenAI, RateLimitError, APIError

client = OpenAI(api_key=os.environ["KUNAVO_API_KEY"], base_url="https://api.kunavo.com/v1")

def call_with_retry(call, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return call()
        except RateLimitError:
            if attempt + 1 == max_attempts: raise
            # 429: exponential backoff with jitter
            time.sleep(min(2 ** attempt, 30) + random.random())
        except APIError as e:
            if e.status_code and 500 <= e.status_code < 600 and attempt + 1 < max_attempts:
                time.sleep(min(2 ** attempt, 30) + random.random())
            else:
                raise

result = call_with_retry(lambda: client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "hi"}],
))

• Begrenzen Sie die Wartezeit pro Versuch auf 30 Sekunden und die Gesamtzahl auf 5 Versuche.
• 4xx-Fehler nicht erneut versuchen (außer 408 und 429). Das kostet nur Zeit.
• Bild- und Videogenerierung sind nicht idempotent: Ein erneuter Versuch ist eine neue Generierung und wird abgerechnet, wenn er gelingt. Ein fehlgeschlagener Aufruf wurde nie abgerechnet, daher kann er gefahrlos wiederholt werden. Für Videos akzeptiert POST /v1/videos einen Idempotency-Key-Header: Eine wiederholte Anfrage mit demselben Schlüssel gibt die erste Aufgabe zurück.
• Bei Chats mit Nebenwirkungen in Ihrem eigenen Code sollten Sie Anfragen mithilfe eines Idempotenzschlüssels auf Anwendungsebene deduplizieren.

Fehlerbehebung im Dashboard

Jeder API-Aufruf — erfolgreich oder fehlgeschlagen — ist unter /app/usage sichtbar. Klicken Sie auf eine beliebige Zeile, um die Detailseite mit der vollständigen Anfrage und Antwort zu öffnen:

• HTTP-Statuscode, der an den Client zurückgegeben wurde.
• Upstream-Fehlercode (falls zutreffend).
• Latenz, IP-Adresse der Anfrage, User-Agent.
• Mit der Statusfilterung lassen sich Muster erkennen (z. B. alle 422-Fehler bei einem bestimmten Modell).

Einen Vorfall melden

Wenn bei einem Modell, das funktionieren sollte, wiederholt 5xx-Fehler auftreten, schreiben Sie an support@kunavo.com und geben Sie Folgendes an:

• Den Modell-Slug und einen Beispiel-Anfragetext (Geheimnisse unkenntlich machen).
• Den Zeitraum, in dem die Fehler aufgetreten sind.
• Den Fehler code + message aus der Antwort.
• Wenn möglich, einen Link zum Nutzungsprotokoll unter /app/usage/[id].

Antwort innerhalb eines Werktags, schneller bei dringenden Problemen mit Auswirkungen auf den Umsatz.

Nächste Schritte

• Wie sich die Abrechnung auf 402- und Kontingentfehler auswirkt
• Verwaltung von API-Schlüsseln