Die Fehlerbehebung für OpenAI-kompatible APIs wird deutlich einfacher, wenn Sie aufhören, jede fehlgeschlagene Anfrage als „der Anbieter ist down“ zu behandeln. Die meisten fehlgeschlagenen Migrationen entstehen auf einer von sechs Ebenen: dem Schlüssel, der Base-URL, der Endpunktfamilie, dem Modellnamen, dem Streaming-Verhalten oder Billing/Readback.
Flatkey hilft Teams dabei, Modellzugriff, Routing, Billing, Nutzungsanalysen und operative Kontrollen an einem Ort zu verwalten, aber ein OpenAI-kompatibler Client benötigt trotzdem eine präzise Konfiguration. Eine Anfrage kann im SDK korrekt aussehen und dennoch fehlschlagen, weil der Client auf das falsche /v1-Root zeigt, der Modellalias zu einer anderen Endpunktfamilie gehört oder der Stream von einem Proxy gepuffert wird.
Verwenden Sie diesen Leitfaden zur Fehlerbehebung für OpenAI-kompatible APIs als sauberen Debug-Pfad, bevor Sie Anwendungscode ändern. Beginnen Sie mit curl, verifizieren Sie eine nicht-streamende Anfrage, fügen Sie dann das SDK hinzu und erweitern Sie erst danach Schritt für Schritt um Streaming, Tools und Produktivverkehr.
Der fünfminütige Pfad zur Fehlerbehebung für OpenAI-kompatible APIs
Bevor Sie Framework-Code prüfen, erfassen Sie die kleinste Anfrage, die funktionieren sollte. Verwenden Sie für Flatkey die Base-URL, die in Ihrer aktuellen Konsole angezeigt wird. Die öffentliche Flatkey-Homepage zeigt derzeit eine Anfrage an https://router.flatkey.ai/v1/chat/completions, was bedeutet, dass SDK-Clients normalerweise das /v1-Root als Base-URL erhalten sollten und das SDK /chat/completions anhängen sollte.
export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-model-alias"
curl -sS "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{"role": "user", "content": "Reply with exactly: ok"}
]
}'
Wenn diese Anfrage fehlschlägt, liegt das Problem nicht an Ihrem App-Framework. Beheben Sie zuerst den Schlüssel, die Base-URL, die Endpunktfamilie oder den Modellalias. Wenn sie erfolgreich ist, übernehmen Sie dieselben Werte in das SDK und fahren Sie von dort mit dem Debugging fort.
Die schnellste Regel zur Fehlerbehebung für OpenAI-kompatible APIs ist einfach: Testen Sie Streaming, Tools, JSON-Modus, Retries oder einen vollständigen Agent-Workflow nicht, bevor eine einfache nicht-streamende Textanfrage erfolgreich ist.
Lesen Sie den Fehler als Ebene, nicht als Urteil
Verwenden Sie den Statuscode, um zu entscheiden, was Sie als Nächstes ändern.
| Symptom | Wahrscheinliche Ebene | Was zuerst geprüft werden sollte |
|---|---|---|
401, invalid_api_key oder Authentifizierungsfehler |
Schlüssel und Auth-Header | Bearer-Format, Schlüsselquelle, kopierte Leerzeichen, Provider-Schlüssel versus Gateway-Schlüssel |
403 oder Zugriff verweigert |
Konto, Projekt oder Richtlinie | IP-Allowlist, Projektmitgliedschaft, Modellfreigabe, Endpunktberechtigung |
404, model_not_found oder unbekanntes Modell |
Modellkatalog und Endpunktfamilie | Exakter Modellalias, aktivierter Modellstatus, /chat/completions versus /responses versus ein anderer Endpunkt |
400 fehlerhaftes Anfrageformat |
Nutzlaststruktur | Erforderliche Felder, nicht unterstützte Parameter, Tool-Schema, Nachrichtenformat |
| Der Stream verbindet sich, aber es erscheinen keine Tokens | Streaming-Pfad | stream: true, SSE-Parser, Pufferung durch Proxy, Stream-Support des Endpunkts |
| Anfrage erfolgreich, aber Nutzungsdaten fehlen | Readback und Billing | Vergleichsanfrage ohne Streaming, Dashboard-Eintrag, Verhalten des finalen Stream-Events |
429, 500, 502, 503 oder 504 |
Rate, Kapazität oder Upstream | Backoff, Anfragevolumen, Statusseite, Retry-Policy, Fallback-Route |
OpenAIs eigener Fehlerleitfaden behandelt 401s als Authentifizierungsprobleme, 429s als Rate- oder Quotenprobleme und 500/503-Antworten als retrybare Server- oder Überlastungszustände. Ein OpenAI-kompatibler Gateway kann eigene Details hinzufügen, daher sollten Sie den Antworttext und die Request-ID aufbewahren, wenn Sie den Fall eskalieren.
Beheben Sie 401s, bevor Sie Modelle ändern
Ein 401 ist der häufigste Umweg bei der Fehlerbehebung für OpenAI-kompatible APIs, weil er wie ein Modell- oder Routingproblem aussieht, obwohl es meist ein Authentifizierungsproblem ist.
Prüfen Sie diese Punkte in dieser Reihenfolge:
- Die Anfrage hat genau einen
Authorization: Bearer ...-Header. - Der Schlüssel ist ein Flatkey-Schlüssel, wenn Sie Flatkey aufrufen, und nicht ein direkter OpenAI-, Anthropic-, Google- oder Test-Schlüssel.
- Der Schlüssel enthält keine mitkopierten Anführungszeichen, keinen Zeilenumbruch, kein unsichtbares Präfix und kein nachgestelltes Leerzeichen.
- Der Schlüssel wird aus der Umgebung geladen, in der Ihr Prozess tatsächlich läuft, nicht nur aus Ihrer Shell.
- Das Konto, Projekt, Team oder die IP-Richtlinie erlaubt die Route.
Verwenden Sie einen kurzen Shell-Check, der den Schlüssel nicht ausgibt:
test -n "$FLATKEY_API_KEY" && echo "key is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c
Wenn curl funktioniert, aber das SDK einen 401 zurückgibt, prüfen Sie die Namen der Umgebungsvariablen. Der Python-Client von OpenAI liest standardmäßig OPENAI_API_KEY, und der Node-Client liest standardmäßig OPENAI_API_KEY. Wenn Ihre App weiterhin OPENAI_API_KEY mit einem alten direkten Provider-Schlüssel exportiert, kann das SDK Ihren neuen Gateway-Schlüssel ignorieren, sofern Sie api_key oder apiKey nicht explizit übergeben.
Beheben Sie die Base-URL, ohne den Endpunkt zu duplizieren
Fehler bei der Base-URL fallen meist in zwei Muster:
- Das SDK erhält den vollständigen Endpunkt, etwa
https://router.flatkey.ai/v1/chat/completions, und hängt dann erneut/chat/completionsan. - Das SDK erhält nur die Domain, etwa
https://router.flatkey.ai, und erreicht nie die OpenAI-kompatible/v1-Route.
Für Python übergeben Sie base_url oder setzen Sie OPENAI_BASE_URL. Die offizielle Python-Client-Quelle fällt außerdem auf https://api.openai.com/v1 zurück, wenn keine benutzerdefinierte Base-URL angegeben wird.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_MODEL"],
messages=[{"role": "user", "content": "Antworte exakt mit: ok"}],
)
print(response.choices[0].message.content)
Für Node übergeben Sie baseURL oder setzen Sie OPENAI_BASE_URL. Der offizielle Node-Client dokumentiert baseURL als Überschreibung für den standardmäßigen OpenAI-API-Root.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_MODEL!,
messages: [{ role: "user", content: "Antworte exakt mit: ok" }],
});
console.log(response.choices[0]?.message?.content);
Wenn dieser Schritt zur Fehlerbehebung bei einer OpenAI-kompatiblen API immer noch fehlschlägt, protokollieren Sie die aufgelöste Base-URL beim Start des Prozesses. Protokollieren Sie nicht den Schlüssel.
Trennen Sie Modellnamen von Endpunktfamilien
„Modell nicht gefunden“ kann bedeuten, dass der Alias falsch ist, aber es kann auch bedeuten, dass der Alias an die falsche Endpunktfamilie gesendet wird. Ein Modell, das für Chat Completions funktioniert, wird über Responses, Messages, Bilder, Video oder Embeddings möglicherweise nicht mit derselben Payload-Struktur bereitgestellt.
Gehen Sie diese Checkliste durch, bevor Sie Modellnamen in der Produktion umbenennen:
| Prüfung | Warum das wichtig ist |
|---|---|
| Bestätigen Sie den exakten Modell-Alias in der aktuellen Flatkey-Konsole | Gateway-Aliase können sich von Marketingnamen direkter Anbieter unterscheiden |
| Bestätigen Sie die Endpunktfamilie | /v1/chat/completions und /v1/responses haben unterschiedliche Request-Strukturen |
| Entfernen Sie optionale Parameter | Eine nicht unterstützte Option kann das eigentliche Modellproblem verdecken |
| Versuchen Sie eine kurze nicht-streamende Anfrage | Eine einfache Anfrage trennt die Route vom Stream-Parsing |
| Protokollieren Sie den fehlgeschlagenen Body und den Zeitstempel | Support- und Audit-Prüfungen benötigen das genaue Modell, die Route und den Fehler |
Die externe Modell-Dokumentation von OpenAI verwendet für benutzerdefinierte Endpunkte dieselbe Idee: eine Endpunkt-URL angeben, Modell-Slugs festlegen und einen Verifizierungscall ausführen. Behandeln Sie Ihr Gateway-Setup genauso. Halten Sie eine kleine freigegebene Modellzuordnung im Code fest, anstatt jeden Dienst rohe Modell-Strings übergeben zu lassen.
Debuggen Sie Streaming erst, nachdem Non-Streaming funktioniert
Streaming sollte ein Test der zweiten Stufe sein. Die Referenz zu OpenAI Chat Completions liefert entweder ein JSON-Objekt für die Chat-Completion oder eine gestreamte Sequenz von Chat-Completion-Chunk-Objekten. Die Responses API unterstützt außerdem text/event-stream, wenn stream aktiviert ist.
Verwenden Sie einen direkten Stream-Probeaufruf:
curl -N "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"stream": true,
"messages": [
{"role": "user", "content": "Zähle langsam von eins bis fünf."}
]
}'
Wenn die nicht-streamende Anfrage funktioniert und der Stream nicht, prüfen Sie den Stream-Pfad:
- Bestätigen Sie, dass die Antwort einen SSE-kompatiblen Content-Type verwendet.
- Deaktivieren Sie Middleware des API-Clients, die die gesamte Antwort puffert, bevor sie zurückgegeben wird.
- Deaktivieren Sie das Buffering des Reverse-Proxys für diese Route.
- Prüfen Sie, ob Ihr Frontend-Parser Chat-Completions-Chunks erwartet, während Ihre Route Responses-Events zurückgibt.
- Vergleichen Sie mit der bestehenden Flatkey-Streaming-Checkliste unter
/blog/openai-compatible-streaming-sse-test.
Dieser Schritt zur Fehlerbehebung bei einer OpenAI-kompatiblen API ist besonders wichtig bei Serverless- und Automatisierungstools. Einige Wrapper geben einen erfolgreichen HTTP-Status zurück und verbergen dabei, dass bis zum Schließen des Streams keine Tokens beim Aufrufer angekommen sind.
Fügen Sie Tools erst hinzu, nachdem die Basisanfrage sauber ist
Tool-Calling fügt eine weitere Fehlerebene hinzu. Ein Gateway, eine Route oder ein ausgewähltes Modell kann einfache Chat-Nachrichten akzeptieren, aber ein Tool-Schema, tool_choice, parallele Tool-Calls oder strenge Einstellungen für strukturierte Ausgaben ablehnen.
Verwenden Sie eine Dreistufen-Reihe von Anfragen:
- Einfache Textanfrage mit demselben Modell.
- Dieselbe Anfrage mit einem kleinen Funktionsschema.
- Vollständiges Produktions-Tool-Schema.
Wenn Anfrage 1 funktioniert und Anfrage 2 fehlschlägt, debuggen Sie nicht mehr Authentifizierung oder Base-URL. Sie debuggen jetzt Modellfähigkeit, Endpunktfamilie oder Schema-Unterstützung. Entfernen Sie optionale Felder, kürzen Sie Beschreibungen und prüfen Sie, ob die gewählte Modellroute das von Ihnen benötigte Tool-Verhalten unterstützt.
Nutzungs- und Billing-Rückmeldung verifizieren
Beenden Sie die Fehlerbehebung für OpenAI-kompatible APIs nicht bei „die Antwort gab Text zurück“. Für eine Migration in die Produktion müssen Sie außerdem nachweisen, dass die Anfrage dort sichtbar ist, wo Finanz- und Betriebsteams sie prüfen werden.
Nach einem erfolgreichen Smoke-Test erfassen Sie:
| Nachweis | Was er belegt |
|---|---|
| Anfragezeitstempel und Route | Welcher Gateway-Pfad Traffic empfangen hat |
| Modell-Alias | Welches konfigurierte Modell angefordert wurde |
| Antwortstatus und Anfrage-ID | Was der Support nachverfolgen kann |
| Usage-Objekt oder Tokenanzahl | Ob die App Kostentreiber erfassen kann |
| Dashboard- oder Billing-Rücklesung | Ob Finance die Ausgaben abgleichen kann |
| Fallback- oder Retry-Ereignis, falls vorhanden | Ob die Routing-Richtlinie den Pfad geändert hat |
Flatkey ist rund um einen Schlüssel, klare Preisgestaltung, einheitliches Billing und ein Dashboard für Schlüssel, Usage und Routing positioniert. Für eine Migration kombinieren Sie den technischen Smoke-Test mit einer Usage-Rückleseprüfung in der Konsole, bevor Sie echten Traffic umstellen.
Ein produktionssicherer Workflow zur Fehlerbehebung
Verwenden Sie diese Abfolge, wenn eine Migration zu einer OpenAI-kompatiblen API fehlschlägt:
- Führen Sie eine einzelne nicht-streamende curl-Anfrage mit der aktuellen Console-Base-URL, einem Schlüssel und einem freigegebenen Modell-Alias aus.
- Beheben Sie zuerst alle 401- oder 403-Fehler, bevor Sie die Nutzdaten ändern.
- Beheben Sie die Zusammensetzung der Base-URL, bevor Sie SDK-Versionen ändern.
- Beheben Sie den Modell-Alias und die Endpoint-Familie, bevor Sie die Retry-Richtlinie ändern.
- Fügen Sie das SDK mit explizitem
api_keyoderapiKeyundbase_urloderbaseURLhinzu. - Fügen Sie Streaming hinzu und verifizieren Sie, dass der Client inkrementelle Events empfängt.
- Fügen Sie Tools oder strukturierten Output jeweils nur eine Funktion auf einmal hinzu.
- Prüfen Sie Usage und Billing-Rücklesung.
- Überführen Sie die funktionierenden Werte in eine rollback-fähige Konfiguration.
Diese Reihenfolge verhindert, dass die Fehlerbehebung für OpenAI-kompatible APIs zu einem Ratespiel wird. Jeder Schritt weist entweder eine Schicht nach oder liefert Ihnen einen kleineren Fehler, den Sie beheben können.
Wann Flatkey hilft
Flatkey ist nützlich, wenn das eigentliche Problem operative Zersplitterung ist: zu viele Provider-Schlüssel, uneinheitlicher Modellzugriff, schwer prüfbare Nutzung und getrennte Billing-Pfade. Ein einheitliches Gateway ersetzt nicht die Notwendigkeit, Endpoint-Familie, Modell-Alias, Streaming, Tools und Billing-Rücklesung zu testen, aber es gibt dem Team einen Ort, an dem diese Prüfungen standardisiert werden können.
Wenn Sie eine App migrieren, kombinieren Sie diesen Leitfaden mit dem Flatkey-Migrationsleitfaden für OpenAI-kompatible APIs unter /blog/openai-compatible-api-migration und der Smoke-Test-Checkliste unter /blog/ai-api-smoke-test-checklist.
Wenn Sie bereit sind, den Workflow mit einem Flatkey-Schlüssel zu testen, beginnen Sie unter /sign-up und halten Sie den ersten Smoke-Test klein genug, um ihn manuell zu prüfen.
Häufig gestellte Fragen
Warum gibt meine OpenAI-kompatible API 401 zurück, obwohl der Schlüssel gesetzt ist?
Der Prozess liest möglicherweise eine andere Umgebungsvariable als die, die Sie geändert haben, oder der Schlüssel gehört möglicherweise zum falschen Anbieter. Prüfen Sie den aufgelösten Variablennamen, den Authorization: Bearer-Header, versehentlich kopierte Leerzeichen sowie eventuelle Konto- oder IP-Richtlinien.
Soll die SDK-Base-URL /chat/completions enthalten?
Meistens nein. Geben Sie dem SDK die /v1-Base-URL und lassen Sie dann das SDK den Endpunkt anhängen. Wenn Sie den vollständigen Endpunkt übergeben, entstehen oft doppelte Pfade.
Warum funktioniert ein Modell ohne Streaming, schlägt aber mit stream: true fehl?
Die Base-Route kann korrekt sein, während der Streaming-Pfad durch Buffering-Middleware, ein SSE-Parser-Mismatch oder eine Route/Modell-Kombination blockiert wird, die kein Streaming unterstützt. Testen Sie mit curl -N, bevor Sie Frontend-Code debuggen.
Warum tritt „model not found“ bei einem gültigen Modellnamen auf?
Der Alias kann in einer Endpoint-Familie gültig und in einer anderen ungültig sein, oder das Gateway stellt möglicherweise einen anderen Alias bereit als der direkte Anbieter. Bestätigen Sie gemeinsam den aktuellen Console-Alias und die Endpoint-Familie.
Was sollte ich testen, bevor ich Produktions-Traffic sende?
Testen Sie eine nicht-streamende Anfrage, eine SDK-Anfrage, einen Stream, einen repräsentativen Tool-Aufruf, falls Ihre App Tools verwendet, einen Fehlerpfad und einen Billing-/Rücklese-Eintrag. Behalten Sie dann eine Rollback-Konfiguration für die vorherige Provider-Route.
Die Fehlerbehebung für OpenAI-kompatible APIs besteht nicht darin, jeden Provider-Fehler auswendig zu lernen. Es geht darum, den Pfad vom Schlüssel zur Base-URL, von der Base-URL zur Endpoint-Familie, von der Endpoint-Familie zum Modell-Alias und von der erfolgreichen Antwort zum Usage-Eintrag nachzuweisen. Wenn diese Schichten klar sind, wird das Umschalten von Traffic über Flatkey zu einer kontrollierten Migration statt zu einer nächtlichen Debugging-Session.
