Fehlerbehebung

Die Form des Fehlers entspricht dem Protokoll, das Sie aufgerufen haben. /v1/chat/completions und /v1/responses geben Fehler im OpenAI-Stil zurück; /v1/messages gibt Fehler im Anthropic-Stil zurück. Die HTTP-Statuscodes sind bei allen drei Protokollen identisch.

Format der Fehlerantwort

OpenAI-Format (/v1/chat/completions, /v1/responses)

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Anthropic-Format (/v1/messages)

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

401 · Authentifizierung fehlgeschlagen authentication_error

{"error":{"message":"missing API key in Authorization header or X-API-Key","type":"authentication_error"}}

Ursachen

• Kein Authorization: Bearer-Header (oder X-API-Key) — Meldung: missing API key in Authorization header or X-API-Key.
• Der Schlüssel entspricht keinem aktiven Schlüssel — Meldung: invalid API key.
• Der Schlüssel ist abgelaufen — Meldung: API key expired.

Lösung

1. Senden Sie Authorization: Bearer sk-syn-… (oder X-API-Key: sk-syn-…).
2. Prüfen Sie, dass der Schlüssel in der Konsole aktiv ist und vollständig kopiert wurde.

400 · Ungültige Anfrage invalid_request

{"error":{"message":"model or models field is required","type":"invalid_request"}}

Ursachen

• Das Feld model fehlt, oder der JSON-Body ist leer oder fehlerhaft.

Lösung

1. Fügen Sie ein model und einen wohlgeformten JSON-Body hinzu. Siehe die Chat-Completions-Referenz.

403 · Kontingent erschöpft quota_exhausted

{"error":{"message":"API key quota exhausted","type":"quota_exhausted"}}

Ursachen

• Das Prepaid-Guthaben des Schlüssels oder Workspaces ist aufgebraucht.

Lösung

1. Laden Sie das Workspace-Guthaben auf. Hinweis: Synthorai gibt bei aufgebrauchtem Guthaben 403 quota_exhausted zurück, nicht 429 — exponentielles Backoff hilft daher nicht; nur ein Aufladen behebt es.

403 · Compliance — keine Datenweitergabe compliance_blocked / compliance_no_data_share

{"error":{"type":"compliance_blocked","code":"compliance_no_data_share","message":"model 'MODEL' is unavailable: your workspace compliance setting disallows providers that retain/train on data"}}

Ursachen

• In Ihrem Workspace ist no_provider_data_share aktiviert, und das angeforderte Modell wird nur von einem Anbieter bereitgestellt, der Datenspeicherung/-weitergabe verlangt (z. B. ein Bedrock- oder Vertex-Modell nur mit Datenweitergabe).

Lösung

1. Leiten Sie die Anfrage an ein Modell ohne Datenspeicherung, oder deaktivieren Sie den Compliance-Schalter des Workspaces, wenn Datenweitergabe für diese Workload akzeptabel ist. Die Aufbewahrungsklasse ist ein Routing-Kriterium pro Modell — siehe die Aufschlüsselung der 30-Tage-Aufbewahrung.

429 · Rate-Limit erreicht rate_limit_exceeded

{"error":{"message":"rate limit exceeded: max 60 requests per minute","type":"rate_limit_exceeded"}}

Ursachen

• Sie haben die Obergrenze für Anfragen pro Minute (RPM) überschritten. Die Meldung nennt das genaue Limit.

Lösung

1. Warten Sie und wiederholen Sie mit exponentiellem Backoff + Jitter (Snippet unten). Beantragen Sie ein höheres Limit, wenn Sie dauerhaften Durchsatz benötigen.

502 · Kein Kanal für das Modell upstream_error

{"error":{"message":"no channels available for model \"MODEL\" in group \"default\"","type":"upstream_error"}}

Ursachen

• Die Modell-id entspricht keinem routbaren Kanal für Ihren Workspace — ein Tippfehler, ein entferntes Modell oder eines, das Ihr Tarif nicht erreichen kann.

Lösung

1. Prüfen Sie die exakte id anhand der aktuellen Modellliste. Wenn ein Modell kürzlich eingestellt wurde, wählen Sie ein aktuelles.

BYOK: Fehler des Upstream-Anbieters

Bei bring-your-own-key läuft die Anfrage auf Ihrem Anbieterkonto (AWS Bedrock, Google Vertex AI oder der Anthropic-API), daher gibt Synthorai den ursprünglichen Fehler des Anbieters unverändert weiter — Antworten enthalten usage.is_byok: true. Die Lösung liegt in der Konsole oder Konfiguration dieses Anbieters, nicht im Gateway. Am häufigsten sind Einstellungen auf Kontoebene für Modellzugriff und Datenweitergabe:

Fehler des Upstream-Anbieters

Diese werden vom Modellanbieter mit dessen eigenem HTTP-Status und type durchgereicht. Nur 500 und 529 weisen auf die Anbieterseite hin; behandeln Sie sie (und 429) als vorübergehend und wiederholen Sie, während 4xx die Anfrage widerspiegeln. Vollständige Referenz: Anthropics Fehlerdokumentation.

Rate-Limits

Rate-Limits werden pro API-Schlüssel durchgesetzt, um eine faire Nutzung für alle Benutzer zu gewährleisten.

Standardlimits

Sie planen den Token-Durchsatz anhand realer Preise pro Token? Lassen Sie Ihre Workload durch den LLM-API-Kostenrechner laufen.

Umgang mit 429-Fehlern

import time
import openai

client = openai.OpenAI(base_url="https://synthorai.io/v1", api_key="YOUR_API_KEY")

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="gpt-5.4-mini",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except openai.RateLimitError as e:
        wait = 2 ** attempt  # exponential backoff
        print(f"Rate limited. Retrying in {wait}s...")
        time.sleep(wait)

async function withRetry(fn, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && attempt < maxAttempts - 1) {
        const wait = Math.pow(2, attempt) * 1000;
        await new Promise(r => setTimeout(r, wait));
      } else throw err;
    }
  }
}

Ein 502 oder Überlastung bei einem Modell? Wählen Sie ein Ausweichmodell aus dem Modellpreisvergleich — jedes routbare Modell und sein Preis pro Token in einer Tabelle.