What Is a Base URL? API Structure, Protocol Choice, and 401/404 Troubleshooting

When an API Key already exists but the client returns 401, 404, 405, model not found, a login page, or HTML instead of JSON, do not change the key, model, and address at the same time. First establish what the Base URL is, then verify the configuration in this order: protocol → root address → version path → endpoint → authentication → model.

A Base URL is the root address of an API server or API gateway. A client library, SDK, or command-line tool appends the path of a specific resource—an endpoint—to create the full request URL.

This guide uses BetterToken in the examples, but the same method applies to other API gateways, self-hosted proxies, and services that implement OpenAI-compatible or Anthropic-compatible protocols.

What is a Base URL in an API?

The simplest formula is:

Full request URL = Base URL + Endpoint Path

For an OpenAI-compatible request:

Base URL:  https://www.bettertoken.ai/v1
Endpoint:  /responses
Full URL:  https://www.bettertoken.ai/v1/responses

Another common endpoint is /chat/completions:

Base URL:  https://www.bettertoken.ai/v1
Endpoint:  /chat/completions
Full URL:  https://www.bettertoken.ai/v1/chat/completions

In real applications, the client usually normalizes the slash between the two parts. The important question is not how to concatenate the strings manually. It is whether the Base URL field already contains a path that the client will append again.

The parts of an API URL

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

Part	Example	Purpose
Scheme	https://	Defines how the connection is established
Host	bettertoken.ai	Identifies the API service
Base path	/v1	Selects an API version or common entry point
Endpoint	/responses	Selects a specific resource or operation

Some services use only a scheme and host as their Base URL. Others include a path such as /v1. There is no universal suffix: use the current documentation for the service and the client.

What a Base URL is not

Often confused with	How it differs from a Base URL
Website home page	A home page may return HTML; an API Base URL is intended for programmatic requests
Full request URL	A full URL already contains an endpoint such as /responses, /chat/completions, or /v1/messages
API Key	The key authenticates the request; the Base URL decides where it is sent
Model ID	The Model ID selects a model; it does not choose the protocol or route
MCP server address	MCP connects tools and data sources; it is not the model API Base URL

A URL opening successfully in a browser is therefore not proof that it is the right Base URL. Many valid API roots do not display a readable page, while a normal login page may belong to the website rather than the API.

Choose the address by client protocol, not by model name

The same model gateway may expose both OpenAI-compatible and Anthropic-compatible entry points. The protocol expected by the client matters more than whether the selected model is called GPT, Claude, Kimi, or GLM.

The current BetterToken documentation uses these rules:

Client or scenario	Typical protocol	Base URL to enter	Path added by the client
Codex	OpenAI Responses	https://www.bettertoken.ai/v1	/responses
Cursor, Cline, OpenCode, and similar tools	OpenAI-compatible	https://www.bettertoken.ai/v1	Chosen by the client, such as /chat/completions
Claude Code	Anthropic-compatible	https://bettertoken.ai	/v1/messages
Raw HTTP request written by you	Depends on the request format	Choose the address for that protocol	Write the endpoint explicitly in code

See OpenAI-compatible vs. Anthropic-compatible APIs for the protocol differences. Do not switch every tool to the Anthropic address merely because you want to call a Claude model, and do not ignore the client’s protocol simply because the model is a GPT model.

Five checks for a Base URL

Change one variable at a time and repeat the same short request after each change. That is the only reliable way to see which layer caused the failure.

1. Confirm the protocol expected by the client

Check the provider or API type in the tool itself:

• Codex uses OpenAI Responses.
• Cursor, Cline, OpenCode, and many similar tools normally use an OpenAI-compatible provider.
• Claude Code uses the Anthropic-compatible Messages protocol.
• A custom script uses whichever request format its code implements.

Changing the model will not repair a protocol mismatch. The request fields, authentication conventions, and endpoint paths can all differ.

2. Enter only the root address, not a complete endpoint

A field named base_url, Base URL, API base, or endpoint base normally expects the shared root.

Correct:

https://www.bettertoken.ai/v1

Common mistakes:

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

If the client appends /responses, the first mistake can produce:

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

For Claude Code, do not put https://www.bettertoken.ai/v1/messages in ANTHROPIC_BASE_URL. Claude Code adds /v1/messages itself.

3. Make sure /v1 appears exactly once

The BetterToken Base URL for OpenAI-compatible clients already contains /v1. If an SDK also exposes api_version, path_prefix, or a similar field, do not add another /v1 unless that SDK explicitly requires it.

This URL in a log almost always points to a joining error:

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

At the other extreme, an OpenAI-compatible request with no /v1 can return 404, website HTML, or a redirect to a login page.

4. Test the endpoint with the smallest possible request

Disable streaming, tools, MCP, and long context. Send one short prompt through the same client, and do not begin with a write-enabled task in a real repository.

Start Codex:

codex

Then enter:

Reply with one short sentence: the connection is working.

Start Claude Code:

claude

Then enter:

Reply with one short sentence: the connection is working.

For a raw HTTP request, use a Model ID currently available in Setup or Model Plaza. The current Codex guide uses gpt-6-astra as an example, but the model available to your key should always come from the dashboard. Only after the minimal request succeeds should you restore streaming, tools, or a longer task.

5. Fully restart the client

Many CLIs, desktop applications, and editor extensions read environment variables and configuration files only at startup. Saving a file does not mean the running process has loaded the new value.

After a change:

1. Close the CLI, desktop app, or editor window.
2. Make sure related background processes have exited.
3. Open a new terminal or restart the app.
4. Repeat the same short request.

Otherwise the file you are looking at may be new while the Base URL under test is still old.

How to read common errors

Symptom	Check first	Next action
404 Not Found	Duplicate /v1, duplicated endpoint, or protocol mismatch	Compare the actual request URL in logs with the client documentation
HTML or a login page	Website route used instead of API route	Check host, /v1, and endpoint
401	API Key, auth variable, and active configuration	Remove accidental spaces from the key and restart the client
403	Whether the key can use the selected model or route	Check model access in Setup or the dashboard
405 Method Not Allowed	HTTP method and endpoint	Confirm whether the route expects POST or another method
model not found	Base URL and protocol before Model ID	Do not hide a routing error by switching models first
Timeout or broken stream	A short non-streaming request	If it succeeds, inspect streaming and timeout settings separately
No change after editing	File location, environment overrides, background process	Fully quit and restart

A 401 does not prove that the URL is correct, and a 404 does not prove that a model is missing. A status code only describes how the server handled the request it received; it does not replace inspection of the actual request URL.

Quick configuration check for Codex and Claude Code

Codex

The address-related part of a Codex configuration should look like this:

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

The API Key is stored in auth.json in the same Codex configuration directory. Follow the complete Codex configuration guide for all fields and authentication rules. Codex appends /responses, so do not include it in base_url.

Claude Code

The address variables for Claude Code are:

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

This fragment highlights only the address and authentication variables. Use the full recommended settings from the Claude Code guide. Do not append /v1 or /messages to ANTHROPIC_BASE_URL.

Four common URL-joining failures

Wrong:  https://www.bettertoken.ai/v1/v1/responses
Cause:  Both the Base URL and the client added /v1

Wrong:  https://www.bettertoken.ai/v1/responses/responses
Cause:  A full endpoint was entered as the Base URL

Wrong:  Claude Code Base URL = https://www.bettertoken.ai/v1/messages
Cause:  Claude Code will append /v1/messages again

Wrong:  An OpenAI-compatible client uses https://bettertoken.ai
Cause:  The /v1 base path required by this entry point is missing

Repair these joins before changing the key, model, or advanced parameters.

What not to do

• Do not change the Base URL, API Key, and Model ID in one step.
• Do not copy one Base URL into every tool.
• Do not infer the protocol from the model name.
• Do not copy an address from an old screenshot or guide without checking current documentation.
• Do not use a real write-enabled project for the first connection test.
• Do not post a full API Key in an issue, chat, or screenshot.
• Do not tune streaming, tools, MCP, or timeouts before a basic request works.

Frequently asked questions

What is a Base URL?

A Base URL is the root address of an API server or gateway. The client adds a specific endpoint, such as /responses, /chat/completions, or /v1/messages.

What is the difference between a Base URL and an endpoint?

A Base URL is the common root used by many requests. An endpoint is the path for one resource or operation. Together they form the full request URL.

Why does a wrong Base URL often return 404?

The usual causes are duplicate /v1, a duplicated endpoint, a missing base path, or a mismatch between an OpenAI-compatible client and an Anthropic-compatible address, or vice versa.

Do all BetterToken Base URLs need /v1?

No. OpenAI-compatible clients such as Codex, Cursor, and Cline normally use https://www.bettertoken.ai/v1. Claude Code uses https://bettertoken.ai and appends /v1/messages itself.

Why did my Base URL change not take effect?

The running process may still have old environment variables or cached configuration. Fully quit the client and its background processes, then start a new terminal or reopen the application.

Are Base URL and MCP the same thing?

No. A Base URL and API Key configure model request routing and authentication. MCP connects external tools, files, databases, and other context. Read MCP vs. API Key and Base URL for a detailed comparison.

Next step

Open the BetterToken documentation, select the tool you actually use, and copy only the current Base URL shown for that tool. Send one short request with your own API Key, with streaming and tools disabled, then check the request time, status, model, and token usage in the Dashboard.

After the basic request succeeds, restore model switching, long context, tools, MCP, and streaming one layer at a time. This separates “is the address correct?” from “does the advanced feature work?” and makes troubleshooting much faster.