Anmerkung des Autors: Wenn curl funktioniert, der Client aber 401, 404 oder 400 meldet oder keine Verbindung aufbaut, helfen sieben Prüfpunkte, eine Fehlercode-Tabelle und eine 10-Minuten-Checkliste.
Mit demselben Schlüssel und demselben Modell liefert eine curl-Anfrage einen 200er-Status. In Cherry Studio, Chatbox, Cursor, Cline, Claude Code oder Codex CLI gibt es dagegen einen 401-, 404- oder 400-Fehler, einen Timeout oder eine leere Antwort. In diesem Fall gilt: Prüfen Sie zuerst die Client-Konfiguration, statt gleich den Schlüssel auszutauschen. Wenn curl funktioniert, zeigt das bereits, dass der Schlüssel gültig und das Netzwerk erreichbar ist. Wahrscheinlich weicht die tatsächlich vom Client gesendete Anfrage von Ihrer Erwartung ab.
Die empfohlene Reihenfolge lautet: Base URL → Protokoll und Endpunkt → Authentifizierungs-Header → Modell-ID → Anfrage-Body → Netzwerk. Prüfen Sie zuvor, ob der Client Ihre geänderte Konfiguration überhaupt eingelesen hat. Dieser Artikel zerlegt den Anfrageweg in sieben Prüfpunkte und beschreibt jeweils: Symptom, Ursache, Überprüfung und Lösung. So können Sie innerhalb von zehn Minuten eingrenzen, ob das Problem beim Client, Gateway oder Upstream-Anbieter liegt.
Dies ist keine weitere Einführung in API-Grundlagen, sondern eine Anleitung zur Fehlerbehebung, die Sie direkt Schritt für Schritt durchgehen können.
Warum curl funktioniert, der Client aber keine Verbindung bekommt: die wichtigsten Prüfpunkte beim API-Proxy
curl prüft nur einen kleinen Teil der Verbindung: DNS-Auflösung, TLS-Handshake, Netzwerkerreichbarkeit, Gültigkeit des API-Schlüssels und die Verfügbarkeit des einen Endpunkts, den Sie manuell aufgerufen haben. Es prüft nicht, ob der Client Ihre geänderte Konfiguration eingelesen hat, wie er die Base URL zusammensetzt oder ob seine Anfrage-Header und sein Request-Body mit denen von curl übereinstimmen.
Eine Anfrage durchläuft vom Client aus ungefähr diese Kette: Client-Konfiguration (Umgebungsvariablen, Konfigurationsdatei, GUI) → Zusammensetzen der Base URL → Protokoll und Endpunkt → Authentifizierungs-Header → Modell-ID und Zuordnung → Request-Body (Nachrichten, Tools, multimodale Inhalte, Streaming) → Proxy, TLS, Netzwerk → Gateway → vorgeschaltetes Modell. Wenn curl funktioniert, bedeutet das nur, dass der von Ihnen manuell gewählte Weg funktioniert. Der Client kann einen ganz anderen Weg nehmen.
| Prüfpunkt | Typisches Symptom | Erste Prüfung |
|---|---|---|
| 1. Konfiguration einlesen | Änderungen bleiben wirkungslos, die Fehlermeldung ist dieselbe wie zuvor | Tatsächliche Anfrage-URL im Client-Log prüfen |
| 2. Base URL zusammensetzen | 404, /v1/v1 oder // im Pfad |
URL im Log mit der curl-URL vergleichen |
| 3. Protokoll und Endpunkt | 404, 400 oder Fehler beim Parsen des Antwortformats | Prüfen, welches Protokoll der Client verwendet |
| 4. Authentifizierungs-Header | 401, obwohl der API-Schlüssel mit curl funktioniert | Unterschiede in den Anfrage-Headern vergleichen |
| 5. Modell-ID | 404 oder 400 mit dem Hinweis, dass das Modell nicht existiert | Zeichen für Zeichen mit der Modellliste des Gateways vergleichen |
| 6. Request-Body | Reiner Text funktioniert, mit Bildern oder Tools folgt ein 400-Fehler | Elemente schrittweise hinzufügen und den Fehler reproduzieren |
| 7. Netzwerk und Streaming | Timeout, stream disconnected, leere Antwort | Streaming zum Vergleich ausschalten, Proxy prüfen |
API-Proxy-Fehlersuche, Punkte 1–2: Client-Konfiguration und Zusammensetzen der Base URL
Prüfpunkt 1: Liest der Client die geänderte Konfiguration überhaupt?
Symptom: Sie haben Base URL und API-Schlüssel geändert, erhalten aber genau dieselbe Fehlermeldung wie zuvor. Oder die Konfiguration funktioniert in einem Projekt, in einem anderen aber nicht.
Ursache: Die meisten Clients beziehen ihre Konfiguration aus mehreren Quellen. Häufig überschreiben GUI-Einstellungen die Umgebungsvariablen. Oder eine Konfigurationsdatei enthält mehrere Profile und aktiv ist nicht das Profil, das Sie geändert haben. Auch Projekteinstellungen können globale Einstellungen überschreiben. Eine weitere Möglichkeit: Ein alter Prozess läuft noch und verwendet weiterhin die Werte, die er beim Start geladen hat. Das passiert besonders leicht bei Kommandozeilentools: Sie ändern eine Umgebungsvariable im Terminal, aber eine bereits laufende IDE oder ein Agent-Prozess bekommt davon nichts mit.
So prüfen Sie es: Öffnen Sie das Client-Log oder die Debug-Ausgabe und prüfen Sie, ob die tatsächlich angefragte URL und die ersten Zeichen des API-Schlüssels den gerade geänderten Werten entsprechen. Falls das Log schwer zugänglich ist, können Sie die Base URL testweise auf eine offensichtlich falsche Adresse setzen. Ändert sich die Fehlermeldung, wissen Sie, dass die Konfiguration übernommen wurde.
So beheben Sie es: Klären Sie zuerst, welche Konfigurationsquellen bei Ihrem Client Vorrang haben. Meist stehen GUI- oder Projekteinstellungen über der globalen Konfigurationsdatei und diese wiederum über den Umgebungsvariablen. Die Regeln unterscheiden sich jedoch je nach Client – massgeblich ist dessen Dokumentation. Ändern Sie den Wert anschliessend nur an der Stelle mit der höchsten Priorität, entfernen Sie widersprüchliche Einträge an anderen Stellen und beenden Sie den Client-Prozess vollständig, bevor Sie ihn neu starten.
Prüfpunkt 2: Abschliessender Schrägstrich, doppeltes /v1 und Pfadpräfix in der Base URL
Symptom: Sie erhalten einen 404-Fehler. Im Log steht eine URL wie /v1/v1/chat/completions oder //chat/completions, oder der Pfad lautet /v1/chat/completions/chat/completions.
Ursache: Das Eingabefeld für die Base URL wird von Clients unterschiedlich interpretiert. Manche erwarten die Stammadresse und hängen /v1 selbst an. Andere erwarten eine Adresse bis einschliesslich /v1 und ergänzen dann /chat/completions. Wieder andere haben separate Eingabefelder für die Base URL und den vollständigen Endpoint. Wenn Sie die komplette Adresse https://api.apiyi.com/v1/chat/completions in ein Feld eintragen, das nur ein Präfix erwartet, oder an eine Adresse mit /v1 noch einen Schrägstrich anhängen, kann ein falscher Pfad entstehen.
So prüfen Sie es: Vergleichen Sie die vollständige Anfrage-URL im Log Zeichen für Zeichen mit der URL, die Sie bei curl verwenden. Achten Sie besonders darauf, wie oft /v1 vorkommt, ob doppelte Schrägstriche enthalten sind und ob am Ende ein Pfadsegment zu viel steht.
So beheben Sie es: Tragen Sie die Adresse entsprechend der Client-Dokumentation ein. Bei OpenAI-kompatiblen Clients ist das üblicherweise https://api.apiyi.com/v1 ohne abschliessenden Schrägstrich. Hängt der Client /v1 automatisch an, entfernen Sie das selbst eingetragene /v1. Prüfen Sie danach die URL im Log erneut und stellen Sie sicher, dass der endgültige Pfad dem Standardformat https://api.apiyi.com/v1/chat/completions entspricht.
🎯 Konfigurationstipp: Die OpenAI-kompatible Zugangsadresse von APIYI (apiyi.com) lautet
https://api.apiyi.com/v1und entspricht damit der Schreibweise des offiziellen OpenAI SDK. Die verfügbaren Modelle finden Sie in der Konsole oder über den Endpunkt für die Modellliste, den Sie mit derselben Base URL aufrufen können. Prüfen Sie damit zunächst, ob API-Schlüssel und Adresse stimmen, bevor Sie den Client konfigurieren.
API-Proxy-Dienst: Prüfpunkte 3–4 – Protokollendpunkte und Authentifizierungsheader
Prüfpunkt 3: Passen Protokoll und Endpunkt zusammen?
Symptom: Die Base URL sieht korrekt aus, trotzdem tritt ein 404- oder 400-Fehler auf. Oder die Anfrage ist erfolgreich, aber der Client meldet, dass er die Antwort nicht verarbeiten kann, oder gibt keinen Inhalt zurück.
Ursache: Für Große Sprachmodelle gibt es mittlerweile mehrere gängige API-Protokolle. Vielleicht unterstützt der Client nur Chat Completions, Sie haben ihn aber auf einen Endpunkt verwiesen, der nur Responses anbietet. Claude Code verwendet das Anthropic-Messages-Protokoll, nicht OpenAI Chat Completions. Auch bei Gemini unterscheiden sich Pfad und Anfragekörper im nativen und im OpenAI-kompatiblen Format vollständig. In curl haben Sie den richtigen Endpunkt von Hand angegeben, während der Client möglicherweise sein eigenes Standardprotokoll verwendet.
| Protokolltyp | Typischer Endpunktpfad | Häufige Nutzer | Authentifizierung |
|---|---|---|---|
| OpenAI Chat Completions | /v1/chat/completions |
Viele Clients wie Cherry Studio, Chatbox und Cline | Authorization: Bearer |
| OpenAI Responses | /v1/responses |
Neuere Tools aus dem OpenAI-Ökosystem | Authorization: Bearer |
| Anthropic Messages | /v1/messages |
Native Anthropic-Tools wie Claude Code | x-api-key und anthropic-version |
| Natives Gemini-Format | Native API mit dem Modellnamen im Pfad | Natives Gemini-SDK | Gemäss offizieller Dokumentation und Gateway-Dokumentation |
So prüfen Sie es: Sehen Sie im Client-Log nach, wie der Anfragepfad endet, um das verwendete Protokoll zu bestimmen. Prüfen Sie dann, ob der gewählte Gateway-Endpunkt dieses Protokoll unterstützt. Falls der Client ein Dropdown für „Anbietertyp“ oder „API-Format“ hat, kontrollieren Sie, ob die Auswahl zum gewünschten Protokoll passt.
So beheben Sie es: Stimmen Sie Protokolltyp, Base URL und Modell im Client aufeinander ab. Für das OpenAI-kompatible Format wählen Sie einen Anbieter vom Typ OpenAI. Native Tools wie Claude Code konfigurieren Sie für das Anthropic-Protokoll; für native Gemini-Funktionen verwenden Sie das Gemini-Format. APIYI unterstützt sowohl das OpenAI-kompatible Format als auch native API-Formate wie Claude und Gemini. Die konkreten Zugangsadressen für die nativen Formate finden Sie in der Dokumentation unter docs.apiyi.com – setzen Sie die Pfade nicht aus dem Gedächtnis zusammen.
Prüfpunkt 4: Passen die Authentifizierungsheader zum Protokoll?
Symptom: Es tritt ein 401-Fehler auf, obwohl derselbe API-Schlüssel mit curl problemlos funktioniert.
Ursache: OpenAI-kompatible APIs verwenden häufig Authorization: Bearer <Key>, native Anthropic-APIs dagegen meist x-api-key und anthropic-version. Manche Plattformen verlangen zusätzlich Header für eine Organisation oder ein Projekt. In curl haben Sie die richtigen Header angegeben, während der Client möglicherweise aufgrund eines anderen Protokolls andere Header sendet. Oder er übermittelt einen Organisationsheader, den das Gateway nicht erkennt. Beides kann dazu führen, dass die Authentifizierung fehlschlägt.
So prüfen Sie es: Vergleichen Sie die Anfrageheader von curl mit denen im Client-Log. Achten Sie besonders auf Felder wie Authorization, x-api-key, Content-Type und OpenAI-Beta. Prüfen Sie auch, ob vor oder nach dem API-Schlüssel überflüssige Leerzeichen, Zeilenumbrüche oder Anführungszeichen stehen. Das passiert häufig beim Kopieren von einer Webseite.
So beheben Sie es: Die Authentifizierungsheader müssen zum Protokoll passen. Ist das richtige Protokoll ausgewählt, senden die meisten Clients automatisch die passenden Header. Falls Sie im Client eigene Anfrageheader festlegen können, entfernen Sie unnötige Organisations- oder Projektheader. Fügen Sie den API-Schlüssel erneut ein und achten Sie darauf, dass er keine überflüssigen Zeichen enthält.
API-Proxy: Prüfpunkte 5–7 – Modell-ID, Request-Body und Netzwerk-Streaming
Prüfpunkt 5: Modell-ID und Modellzuordnung
Symptom: Ein 404- oder 400-Fehler meldet, dass das Modell nicht existiert oder ungültig ist. Oder nur ein bestimmtes Modell schlägt fehl, während andere funktionieren.
Ursache: Die Modell-ID muss zeichengetreu mit der Modellliste des Gateways übereinstimmen. Häufige Unterschiede betreffen Groß- und Kleinschreibung, Versionssuffixe, Präfixe wie provider/model und Aliase. Dasselbe Modell kann auf verschiedenen Plattformen unterschiedlich heißen. Möglicherweise fehlt die gewünschte ID auch in der integrierten Modellliste des Clients, sodass dieser stillschweigend auf einen Standardwert ausweicht.
So prüfen Sie es: Kopieren Sie die Modell-ID aus der Modelllisten-Schnittstelle oder der Konsole des Gateways und vergleichen Sie sie Zeichen für Zeichen mit dem Feld model im Request-Body des Client-Logs. Schlägt nur ein bestimmtes Modell fehl, prüfen Sie zuerst, ob Modell-ID und Endpunkt zusammenpassen. Prüfen Sie anschließend, ob das Konto Zugriff auf das Modell hat.
So beheben Sie es: Fügen Sie im Client manuell ein benutzerdefiniertes Modell hinzu und fügen Sie die ID direkt aus dem Gateway ein, statt sie abzutippen. Wenn der Client Modelle zuordnet, prüfen Sie, ob der Name nach der Zuordnung korrekt ist.
💡 Tipp zur Modell-ID: Wenn Sie über APIYI apiyi.com mit einem API-Schlüssel Modelle verschiedener Anbieter wie OpenAI, Claude, Gemini, DeepSeek und Qwen aufrufen, ist die Modellliste in der Konsole maßgeblich. Da Plattformen dasselbe Modell unterschiedlich benennen können, kopieren Sie die ID am besten direkt aus der Konsole. Angaben zur Verfügbarkeit der Modelle finden Sie ebenfalls in der Konsole und in der Dokumentation.
Prüfpunkt 6: Request-Body und multimodale Formate
Symptom: Reine Textgespräche funktionieren. Sobald Sie aber ein Bild senden, ein Tool aufrufen oder Reasoning-Parameter aktivieren, tritt ein 400-Fehler auf.
Ursache: Kompatibilitätsprobleme im Request-Body entstehen häufig an diesen Stellen: bei der Struktur des multimodalen content-Arrays, der Schreibweise des Feldes image_url oder einem fehlenden MIME-Präfix wie data:image/png;base64, bei Base64-Bildern. Auch das Format der Tool-Call-Felder kann vom aktuellen Protokoll abweichen. Zudem unterscheiden sich die Anforderungen an max_tokens und max_completion_tokens je nach Modell, und Reasoning-Parameter werden nur von einigen Modellen akzeptiert. Die Parameter verschiedener Anbieter sind nicht vollständig austauschbar.
So prüfen Sie es: Fügen Sie die Funktionen schrittweise hinzu. Senden Sie zuerst reinen Text, aktivieren Sie nach einem erfolgreichen Test Streaming, ergänzen Sie dann Tool-Aufrufe und zuletzt multimodale Inhalte. Testen Sie nach jedem Schritt erneut. Wo der Fehler erstmals auftritt, liegt das Problem im entsprechenden Feld. Die Fehlermeldung nennt das betroffene Feld meist konkret – sehen Sie sich daher die vollständige Fehlerantwort an.
So beheben Sie es: Deaktivieren Sie nicht benötigte erweiterte Parameter im Client und passen Sie die Felder anhand der Dokumentation des Zielmodells an. Verwenden Sie für Bilder ein korrektes Base64-Präfix oder eine erreichbare URL und schreiben Sie Tool-Definitionen im Format des aktuellen Protokolls.
Prüfpunkt 7: Netzwerk, Proxy, TLS und Streaming-Pufferung
Symptom: Die Verbindung läuft in ein Timeout, stream disconnected erscheint, nach langer Wartezeit kommt eine leere Antwort zurück oder Anfragen ohne Streaming funktionieren, während Streaming fehlschlägt.
Ursache: Möglicherweise nutzt der Client einen System-Proxy oder einen über Umgebungsvariablen konfigurierten Proxy, curl dagegen nicht – oder umgekehrt. Auch eine Unternehmens-Firewall, die TLS-Zertifikatsprüfung, die IPv6-Auflösung oder DNS können verhindern, dass der Client eine Verbindung herstellt. Beim Streaming puffern manche Proxys die Antwort und leiten sie erst weiter, wenn der gesamte Inhalt vorliegt. Erhält der Client in der Zwischenzeit keine Daten, meldet er ein Timeout oder einen Verbindungsabbruch.
So prüfen Sie es: Unterscheiden Sie zunächst zwischen „Verbindung nicht aufgebaut“ und „Stream unterbrochen“. Im ersten Fall suchen Sie nach TLS- oder Verbindungsfehlern; im zweiten Fall wurden meist bereits Teile der Antwort empfangen. Deaktivieren Sie Streaming und versuchen Sie es erneut. Funktioniert die Anfrage dann, liegt die Ursache wahrscheinlich an der Proxy-Pufferung oder den Timeout-Einstellungen. Prüfen Sie, ob die Proxy-Umgebungsvariablen im Client und im Terminal übereinstimmen.
So beheben Sie es: Stimmen Sie die Proxy-Einstellungen von Client und curl aufeinander ab. Schliessen Sie puffernde Proxys für Streaming-Anfragen aus und erhöhen Sie bei Bedarf das Client-Timeout. Bei gelegentlichen Unterbrechungen beim Upstream-Anbieter können Sie die Anfrage begrenzt oft wiederholen oder vorübergehend zu einem anderen Modell wechseln, um zu prüfen, ob das Problem nur einen Upstream-Anbieter betrifft.
API-Proxy-Dienst: Fehlercodes und Checkliste für die Client-Konfiguration
Grenzen Sie den Fehler zunächst anhand des Fehlercodes ein und prüfen Sie anschließend die Konfiguration Punkt für Punkt.
Übersicht der Fehlercodes
| Fehlercode | Häufige Ursachen | Zuerst prüfen |
|---|---|---|
| 401 | API-Schlüssel ungültig, abgelaufen oder deaktiviert; falsches Format des Request-Headers; Organisation oder Projekt stimmt nicht überein | Prüfpunkte 1, 4 |
| 403 | API-Schlüssel gültig, aber durch Modell-, Organisations- oder Regionsrichtlinien abgelehnt; IP-Whitelist; Modell nicht freigeschaltet | Prüfpunkt 5, Kontoberechtigungen |
| 404 | Falscher Base-URL-Pfad; Endpunkt oder Modell-ID existiert nicht; Route im Gateway nicht implementiert | Prüfpunkte 2, 3, 5 |
| 400 | Ungültiger Request-Body, Parameter, Modell-ID oder multimodale Felder; inkompatible Anbieterparameter | Prüfpunkte 5, 6 |
| 429 | Ratenlimit erreicht oder Kontingent erschöpft | Retry-After prüfen, mit zunehmendem Abstand erneut versuchen oder Modell wechseln |
| 500/502/503/529 | Fehler beim vorgelagerten Anbieter oder Gateway; 529 deutet häufig auf Überlastung hin | Begrenzt erneut versuchen, Gateway-Logs prüfen |
| Timeout, stream disconnected | Unterbrechung im Netzwerk, Proxy, bei TLS oder beim vorgelagerten Anbieter | Prüfpunkt 7 |
Checkliste für die Client-Konfiguration
| Prüfpunkt | Was zu prüfen ist |
|---|---|
| Konfigurationsquelle | Werden Umgebungsvariablen, eine Konfigurationsdatei oder die GUI geändert? Was hat die höchste Priorität? Gibt es mehrere Profile oder überschreibende Projektkonfigurationen? |
| Base URL | Enthält sie /v1? Fügt der Client /v1 automatisch hinzu? Gibt es am Ende einen überflüssigen Schrägstrich? |
| Endpunkttyp | Chat Completions, Responses oder die native Claude- beziehungsweise Gemini-API? Unterstützt die Client-Version den jeweiligen Typ? |
| Authentifizierungs-Header | Wird Authorization: Bearer oder x-api-key verwendet? Ist anthropic-version erforderlich? |
| Modell-ID | Stimmt sie einschließlich Groß- und Kleinschreibung sowie Präfix exakt mit der Modellliste des Gateways überein? |
| Request-Body | Enthält er Tools, Bilder oder Reasoning-Parameter? Ist das Feld max_tokens für das Zielmodell geeignet? |
| Streaming und Netzwerk | Ist Streaming aktiviert? Puffert der Proxy die Daten? Stimmen die Proxy-Einstellungen von Client und curl überein? |
Fehler mit einer minimalen Anfrage reproduzieren
Am effektivsten ist ein Vergleich unter gleichen Bedingungen: Senden Sie dieselbe Anfrage mit derselben Base URL, demselben API-Schlüssel, Modell und Request-Body zuerst mit curl und dann mit dem Client. Gehen Sie dabei so vor:
- Prüfen Sie API-Schlüssel und Base URL über die Modelllisten-API, zum Beispiel mit einer Anfrage an
https://api.apiyi.com/v1/models; - Prüfen Sie Endpunkt und Modell-ID mit einer minimalen reinen Text-Chat-Anfrage;
- Aktivieren Sie Streaming, um Netzwerk und Proxy zu prüfen;
- Ergänzen Sie Tool-Aufrufe oder multimodale Inhalte, um den Request-Body zu prüfen;
- Sehen Sie bei jedem Schritt sowohl in die Client-Logs als auch in die Gateway-Logs.
🚀 Tipp zur Fehlersuche: In der APIYI-Konsole können Sie Nutzungsstatistiken und detaillierte Aufruf-Logs einsehen. Meldet der Client einen Fehler, aber in der Konsole gibt es keinen Eintrag für den Aufruf, hat die Anfrage das Gateway nicht erreicht. Das Problem liegt dann in der Client-Konfiguration oder im lokalen Netzwerk. Ist ein Eintrag mit einer Fehlermeldung vorhanden, können Sie anhand der Logs erkennen, ob das Problem an den Parametern oder beim vorgelagerten Anbieter liegt.
Häufige Fragen (FAQ)
Q1: Hilft ein neuer Key, wenn curl funktioniert, der Client aber keine Verbindung herstellen kann?
Meistens nicht. Wenn curl funktioniert, ist der Key gültig. Wenn ein neuer Key das Problem scheinbar löst, liegt das oft daran, dass beim Wechsel auch der Client neu gestartet oder das Profil gewechselt und die Konfiguration dadurch neu geladen wurde. Beenden Sie daher den Client vollständig und starten Sie ihn neu, statt den Key zu wechseln. Prüfen Sie anschließend in den Logs, welche Base URL und welcher Key tatsächlich verwendet werden. In der APIYI-Konsole können Sie den Status und die Aufrufprotokolle des Keys prüfen, um ein tatsächliches Problem mit dem Key zu erkennen.
Q2: Warum funktioniert der Endpunkt /models, aber die Chat-Anfrage nicht?
Der Endpunkt für die Modellliste bestätigt nur, dass die Authentifizierung und die Base URL grundsätzlich stimmen. Er prüft weder den Chat-Endpunkt noch die Modell-ID oder den Request-Body. Wenn Chat-Anfragen fehlschlagen, prüfen Sie der Reihe nach: Passt das vom Client verwendete Protokoll zum Endpunkt (Prüfpunkt 3)? Stimmt die Modell-ID exakt mit dem Eintrag in der Liste überein (Prüfpunkt 5)? Enthält der Request-Body Parameter, die das Zielmodell nicht unterstützt (Prüfpunkt 6)?
Q4: Nur ein bestimmtes Modell schlägt fehl, alle anderen funktionieren. Was sollte ich zuerst prüfen?
Prüfen Sie zuerst die Modell-ID und den Endpunkt, danach die Kontoberechtigungen. Am häufigsten sind Unterschiede bei Gross- und Kleinschreibung, Präfixen oder Aliasnamen der Modell-ID. Eine weitere mögliche Ursache ist, dass das Modell ein anderes Protokoll benötigt, etwa das native Format. Erst danach kommen Probleme mit Berechtigungen oder Verfügbarkeit infrage. Mit APIYI können Sie mit einem einzigen Key zwischen Modellen verschiedener Anbieter wechseln. Testen Sie vorübergehend ein vergleichbares Modell, um schnell einzugrenzen, ob das Problem nur ein einzelnes Modell oder die gesamte Konfiguration betrifft.
Q5: Wie erkenne ich, ob das Problem beim Client oder beim Gateway liegt?
Entscheidend sind zwei Fragen: Hat das Gateway die Anfrage erhalten? Und funktioniert dieselbe Anfrage mit curl? Gibt es im Gateway keinen Eintrag, liegt das Problem in der Regel beim Client oder im lokalen Netzwerk. Funktioniert dieselbe Anfrage mit curl, schlägt aber im Client fehl, liegt es meist daran, wie der Client die Anfrage zusammensetzt, oder am Request-Body. Schlägt dieselbe Anfrage auch mit curl fehl und zeigen die Logs einen 5xx-Fehler, sollten Sie den Gateway-Support kontaktieren.
Fazit: 10-Minuten-Checkliste für API-Proxys und der richtige Zeitpunkt für Hilfe
Wenn „curl funktioniert, aber der Client keine Verbindung aufbaut“, tauschen Sie nicht gleich den API-Schlüssel aus. Gehen Sie stattdessen diese Checkliste durch – das dauert etwa 10 Minuten:
- Client-Logs prüfen: Ermitteln Sie die tatsächlich verwendete URL sowie Request-Header und -Body und stellen Sie sicher, dass die Konfiguration wirksam ist.
- Base URL prüfen:
/v1darf nur einmal vorkommen; doppelte Schrägstriche und wiederholte Pfadsegmente vermeiden. - Endpunktprotokoll prüfen: Chat Completions, Responses, Claude Messages oder natives Gemini-Format – das Protokoll muss zum Client passen.
- Authentifizierungs-Header prüfen:
Authorization: Beareroderx-api-keyverwenden; überflüssige Organisations-Header und Leerzeichen am Anfang oder Ende des API-Schlüssels entfernen. - Modell-ID prüfen: Zeichen für Zeichen mit der Modellliste des Gateways vergleichen.
- Minimale Anfrage senden: Dieselbe Anfrage mit demselben API-Schlüssel, Modell und Request-Body einmal mit curl und einmal mit dem Client senden und die Ergebnisse vergleichen.
- Streaming hinzufügen: Schlägt die Anfrage fehl, Proxy-Pufferung und Timeouts prüfen.
- Tools oder multimodale Inhalte hinzufügen: Schlägt die Anfrage fehl, die Felder im Request-Body prüfen.
- Ursache eingrenzen: Anhand der Gateway-Logs entscheiden, ob das Problem beim Client oder beim Gateway liegt.
Wann liegt ein Client-Bug vor? Wenn das Gateway keinen Aufruf protokolliert oder curl mit exakt derselben URL und denselben Headern und demselben Body erfolgreich ist, während der Client scheitert – und Sie bereits bestätigt haben, dass die Konfiguration stimmt und die Client-Version den Endpunkt unterstützt. Aktualisieren Sie in diesem Fall den Client oder melden Sie das Problem beim Client-Projekt.
Wann sollten Sie den Gateway-Support kontaktieren? Wenn dieselbe minimale Anfrage auch mit curl fehlschlägt und die Gateway-Logs den Aufruf mit einem 5xx-Fehler zeigen. Oder wenn ein Modell dauerhaft Fehler meldet, andere Modelle aber funktionieren und Sie Probleme mit der Modell-ID und den Berechtigungen ausgeschlossen haben. Geben Sie bei der Kontaktaufnahme den Anfragezeitpunkt, die Modell-ID, den Fehlercode und die Fehlermeldung aus den Logs an – so lässt sich die Ursache schneller finden.
Für Team-Tools, die zuverlässig funktionieren müssen, sind mehrere Modelle und Verbindungswege selbst ein Mittel zur Fehlersuche: Fällt ein Modell oder Verbindungsweg aus, können Sie zum Vergleich auf ein anderes Modell wechseln und den Fehlerbereich sofort eingrenzen. Mit APIYI auf apiyi.com greifen Sie mit einem API-Schlüssel auf das OpenAI-kompatible Format sowie die nativen Formate von Claude und Gemini zu. Nutzungsdaten und Logs in der Konsole helfen bei der schnellen Überprüfung. Maßgeblich für Preise und Verfügbarkeit sind die Konsole und die Dokumentation.
Autor: APIYI-Technikteam
Technischer Austausch: Kontaktieren Sie uns über die Startseite von APIYI.
