Was ist eine Base URL? API-Aufbau und Fehler 401/404 beheben

Wenn der API Key bereits erstellt ist, der Client aber 401, 404, 405, model not found, eine Anmeldeseite oder HTML statt JSON zurückgibt, ändern Sie nicht gleichzeitig Key, Modell und Adresse. Klären Sie zuerst, was die Base URL ist, und prüfen Sie die Konfiguration anschließend in dieser Reihenfolge: Protokoll → Stammadresse → API-Version → Endpoint → Authentifizierung → Modell.

Eine Base URL ist die Stammadresse eines API-Servers oder API-Gateways. Eine Client-Bibliothek, ein SDK oder ein Kommandozeilenwerkzeug ergänzt den Pfad einer bestimmten Ressource — den Endpoint — und bildet so die vollständige Request-URL.

Die Beispiele verwenden BetterToken. Die Methode gilt ebenso für andere API-Gateways, selbst betriebene Proxys und Dienste mit OpenAI- oder Anthropic-kompatiblen Protokollen.

Was ist eine Base URL in einer API?

Die einfachste Formel lautet:

Vollständige Request-URL = Base URL + Endpoint-Pfad

Beispiel für einen OpenAI-kompatiblen Request:

Base URL:  https://www.bettertoken.ai/v1
Endpoint:  /responses
Vollständige URL: https://www.bettertoken.ai/v1/responses

Ein weiterer häufig verwendeter Endpoint ist /chat/completions:

Base URL:  https://www.bettertoken.ai/v1
Endpoint:  /chat/completions
Vollständige URL: https://www.bettertoken.ai/v1/chat/completions

In einer echten Anwendung normalisiert der Client üblicherweise den Schrägstrich zwischen beiden Teilen. Entscheidend ist nicht, wie Sie Strings von Hand verbinden, sondern ob das Base-URL-Feld bereits einen Pfad enthält, den der Client später noch einmal anhängt.

Bestandteile einer API-URL

Betrachten wir https://www.bettertoken.ai/v1/responses:

Teil	Beispiel	Aufgabe
Schema	https://	Legt die Art der Verbindung fest
Host	bettertoken.ai	Identifiziert den API-Dienst
Basispfad	/v1	Wählt eine API-Version oder einen gemeinsamen Einstieg
Endpoint	/responses	Wählt eine bestimmte Ressource oder Aktion

Bei manchen Diensten besteht die Base URL nur aus Schema und Domain. Bei anderen gehört ein Pfad wie /v1 dazu. Es gibt keinen universellen Suffix; maßgeblich sind die aktuellen Dokumentationen des Dienstes und des Clients.

Was eine Base URL nicht ist

Häufige Verwechslung	Unterschied
Startseite der Website	Sie kann HTML liefern; eine API Base URL ist für programmatische Requests gedacht
Vollständige Request-URL	Sie enthält bereits einen Endpoint wie /responses, /chat/completions oder /v1/messages
API Key	Der Key authentifiziert; die Base URL bestimmt das Ziel
Model ID	Sie wählt das Modell, aber nicht Protokoll oder Route
MCP-Serveradresse	MCP verbindet Tools und Daten; es ersetzt nicht die Base URL der Modell-API

Dass sich eine Adresse im Browser öffnen lässt, beweist daher nicht, dass sie die richtige Base URL ist. Viele gültige API-Wurzeln zeigen keine lesbare Seite. Umgekehrt kann eine funktionierende Anmeldeseite zur Website gehören und nicht zur API.

Adresse nach Client-Protokoll wählen, nicht nach Modellname

Dasselbe Modell-Gateway kann OpenAI-kompatible und Anthropic-kompatible Einstiege anbieten. Welches Protokoll der Client erwartet, ist wichtiger als der Name GPT, Claude, Kimi oder GLM.

Die aktuelle BetterToken-Dokumentation verwendet folgende Zuordnung:

Client oder Szenario	Typisches Protokoll	Einzutragende Base URL	Vom Client ergänzter Pfad
Codex	OpenAI Responses	https://www.bettertoken.ai/v1	/responses
Cursor, Cline, OpenCode und ähnliche Tools	OpenAI-compatible	https://www.bettertoken.ai/v1	Passender Endpoint, etwa /chat/completions
Claude Code	Anthropic-compatible	https://bettertoken.ai	/v1/messages
Eigener HTTP-Request	Abhängig vom Format	Adresse des gewählten Protokolls	Endpoint wird im Code angegeben

Lesen Sie dazu OpenAI-kompatible und Anthropic-kompatible APIs. Verwenden Sie nicht in jedem Tool die Anthropic-Adresse, nur weil Sie ein Claude-Modell aufrufen möchten. Auch ein GPT-Modell hebt die Protokollanforderung des Clients nicht auf.

Fünf Prüfungen für die Base URL

Ändern Sie jeweils nur eine Variable und wiederholen Sie nach jeder Änderung denselben kurzen Request. Nur so erkennen Sie, welche Ebene den Fehler verursacht hat.

1. Erwartetes Protokoll des Clients bestimmen

Prüfen Sie den Provider oder API-Typ im Tool:

• Codex verwendet OpenAI Responses.
• Cursor, Cline, OpenCode und viele ähnliche Tools nutzen gewöhnlich einen OpenAI-compatible Provider.
• Claude Code verwendet das Anthropic-compatible Messages-Protokoll.
• Bei einem eigenen Skript bestimmt das implementierte Request-Format das Protokoll.

Ein Modellwechsel behebt keinen Protokollkonflikt. Request-Felder, Authentifizierung und Endpoint-Pfade können sich unterscheiden.

2. Nur die Stammadresse eintragen, keinen vollständigen Endpoint

Ein Feld namens base_url, Base URL, API base oder endpoint base erwartet normalerweise die gemeinsame Wurzel.

Richtig:

https://www.bettertoken.ai/v1

Häufige Fehler:

https://www.bettertoken.ai/v1/responses
https://www.bettertoken.ai/v1/chat/completions

Wenn der Client /responses selbst ergänzt, kann aus dem ersten Fehler Folgendes werden:

https://www.bettertoken.ai/v1/responses/responses

Tragen Sie bei Claude Code auch nicht https://www.bettertoken.ai/v1/messages in ANTHROPIC_BASE_URL ein. Claude Code ergänzt /v1/messages selbst.

3. Sicherstellen, dass /v1 genau einmal vorkommt

Die BetterToken Base URL für OpenAI-kompatible Clients enthält /v1 bereits. Bietet das SDK zusätzlich api_version, path_prefix oder ein ähnliches Feld, fügen Sie kein zweites /v1 hinzu, außer die SDK-Dokumentation fordert es ausdrücklich.

Diese URL im Log weist fast immer auf einen Verknüpfungsfehler hin:

https://www.bettertoken.ai/v1/v1/responses

Umgekehrt kann ein OpenAI-kompatibler Request ohne /v1 zu 404, Website-HTML oder einer Weiterleitung zur Anmeldung führen.

4. Endpoint mit einem minimalen Request testen

Deaktivieren Sie streaming, tools, MCP und lange Kontexte. Senden Sie über denselben Client nur einen kurzen Satz. Beginnen Sie nicht mit einer schreibenden Aufgabe in einem echten Repository.

Codex starten:

codex

Dann eingeben:

Antworte mit genau einem kurzen Satz: Die Verbindung funktioniert.

Claude Code starten:

claude

Dann eingeben:

Antworte mit genau einem kurzen Satz: Die Verbindung funktioniert.

Für einen direkten HTTP-Request verwenden Sie eine aktuell in Setup oder Model Plaza verfügbare Model ID. Der derzeitige Codex-Leitfaden nutzt gpt-6-astra als Beispiel; welche Modelle für Ihren Key verfügbar sind, zeigt das Dashboard. Aktivieren Sie streaming, tools oder lange Aufgaben erst wieder, wenn der Minimaltest erfolgreich war.

5. Client vollständig neu starten

Viele CLIs, Desktop-Anwendungen und Editor-Erweiterungen lesen Umgebungsvariablen und Konfigurationsdateien nur beim Start. Das Speichern der Datei bedeutet nicht, dass der laufende Prozess den neuen Wert geladen hat.

Nach einer Änderung:

1. CLI, Desktop-App oder Editorfenster schließen.
2. Sicherstellen, dass zugehörige Hintergrundprozesse beendet sind.
3. Ein neues Terminal öffnen oder die Anwendung neu starten.
4. Denselben kurzen Test wiederholen.

Andernfalls betrachten Sie möglicherweise die neue Datei, testen aber weiterhin die alte Base URL.

Häufige Fehler richtig einordnen

Symptom	Zuerst prüfen	Nächster Schritt
404 Not Found	Doppeltes /v1, wiederholter Endpoint, falsches Protokoll	Tatsächliche Request-URL im Log mit der Dokumentation vergleichen
HTML oder Anmeldeseite	Webroute statt API-Route	Host, /v1 und Endpoint prüfen
401	API Key, Auth-Variable, aktive Konfiguration	Leerzeichen am Key entfernen und Client neu starten
403	Zugriff des Keys auf Modell oder Route	Verfügbarkeit in Setup oder Dashboard prüfen
405 Method Not Allowed	HTTP-Methode und Endpoint	Prüfen, ob POST oder eine andere Methode erwartet wird
model not found	Base URL und Protokoll vor Model ID	Routingfehler nicht durch Modellwechsel verdecken
Timeout oder abgebrochener Stream	Kurzer Request ohne streaming	Bei Erfolg streaming und timeout getrennt prüfen
Keine Änderung nach Bearbeitung	Dateipfad, überschreibende Variablen, Prozess	Vollständig beenden und neu starten

Ein 401 beweist nicht, dass die URL richtig ist, und ein 404 beweist nicht, dass das Modell fehlt. Der Statuscode beschreibt nur, wie der Server auf den empfangenen Request reagiert hat.

Schnelle Prüfung für Codex und Claude Code

Codex

Der adressbezogene Teil der Codex-Konfiguration sollte so aussehen:

model_provider = "bettertoken"
model = "gpt-6-astra"
cli_auth_credentials_store = "file"

[model_providers.bettertoken]
name = "BetterToken"
base_url = "https://www.bettertoken.ai/v1"
wire_api = "responses"
requires_openai_auth = true

Der API Key liegt in auth.json im selben Codex-Konfigurationsverzeichnis. Alle Felder und Authentifizierungsregeln finden Sie im Codex-Leitfaden. Codex ergänzt /responses; nehmen Sie es daher nicht in base_url auf.

Claude Code

Die zentralen Adress- und Authentifizierungsvariablen lauten:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://bettertoken.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY"
  }
}

Dieser Ausschnitt hebt nur Adresse und Token hervor. Verwenden Sie die vollständige empfohlene Konfiguration aus dem Claude-Code-Leitfaden. Hängen Sie weder /v1 noch /messages an ANTHROPIC_BASE_URL an.

Vier typische Fehler beim Zusammensetzen der URL

Falsch:  https://www.bettertoken.ai/v1/v1/responses
Ursache: Base URL und Client haben beide /v1 ergänzt

Falsch:  https://www.bettertoken.ai/v1/responses/responses
Ursache: Ein vollständiger Endpoint wurde als Base URL eingetragen

Falsch:  Claude Code Base URL = https://www.bettertoken.ai/v1/messages
Ursache: Claude Code ergänzt /v1/messages erneut

Falsch:  OpenAI-compatible Client verwendet https://bettertoken.ai
Ursache: Der für diesen Einstieg erforderliche Basispfad /v1 fehlt

Beheben Sie diese Verknüpfungen, bevor Sie Key, Modell oder erweiterte Parameter ändern.

Was Sie nicht tun sollten

• Base URL, API Key und Model ID nicht gleichzeitig ändern.
• Nicht dieselbe Base URL in jedes Tool kopieren.
• Das Protokoll nicht aus dem Modellnamen ableiten.
• Keine Adresse aus einem alten Screenshot oder Leitfaden übernehmen, ohne die aktuelle Dokumentation zu prüfen.
• Für den ersten Verbindungstest kein echtes Projekt mit Schreibrechten verwenden.
• Den vollständigen API Key nicht in Issues, Chats oder Screenshots veröffentlichen.
• streaming, tools, MCP oder timeout nicht optimieren, bevor ein einfacher Request funktioniert.

Häufig gestellte Fragen

Was ist eine Base URL?

Sie ist die Stammadresse eines API-Servers oder Gateways. Der Client ergänzt einen Endpoint wie /responses, /chat/completions oder /v1/messages.

Was ist der Unterschied zwischen Base URL und Endpoint?

Die Base URL ist die gemeinsame Wurzel vieler Requests. Der Endpoint ist der Pfad einer bestimmten Ressource oder Aktion. Zusammen bilden sie die vollständige Request-URL.

Warum führt eine falsche Base URL oft zu 404?

Typische Ursachen sind ein doppeltes /v1, ein doppelter Endpoint, ein fehlender Basispfad oder eine Unvereinbarkeit zwischen OpenAI-kompatiblem Client und Anthropic-kompatibler Adresse beziehungsweise umgekehrt.

Benötigen alle BetterToken Base URLs /v1?

Nein. Codex, Cursor, Cline und andere OpenAI-kompatible Clients verwenden normalerweise https://www.bettertoken.ai/v1. Claude Code verwendet https://bettertoken.ai und ergänzt /v1/messages.

Warum wurde meine Änderung der Base URL nicht übernommen?

Der laufende Prozess kann alte Umgebungsvariablen oder eine zwischengespeicherte Konfiguration nutzen. Beenden Sie Client und Hintergrundprozesse vollständig und öffnen Sie ein neues Terminal oder starten Sie die Anwendung neu.

Sind Base URL und MCP dasselbe?

Nein. Base URL und API Key konfigurieren Routing und Authentifizierung von Modell-Requests. MCP verbindet externe Tools, Dateien, Datenbanken und weiteren Kontext. Mehr dazu: MCP im Vergleich zu API Key und Base URL.

Nächster Schritt

Öffnen Sie die BetterToken-Dokumentation, wählen Sie das tatsächlich verwendete Tool und kopieren Sie nur die dort aktuell angegebene Base URL. Senden Sie mit Ihrem API Key einen kurzen Request ohne streaming und tools und prüfen Sie im Dashboard Zeit, Status, Modell und Token-Verbrauch.

Wenn der Basis-Request funktioniert, aktivieren Sie Modellwechsel, langen Kontext, tools, MCP und streaming jeweils einzeln. So trennen Sie die Fragen „Ist die Adresse korrekt?“ und „Funktioniert die erweiterte Funktion?“ und finden den Fehler deutlich schneller.