Ошибки и стабильность

Что такое Base URL в API и как исправить ошибки 401, 404 и endpoint

Base URL — это базовый адрес API-сервера или шлюза, к которому клиент добавляет конкретный endpoint. В статье показано, как отличить Base URL от полного URL, выбрать правильный адрес для OpenAI-compatible клиентов и Claude Code, а затем последовательно проверить протокол, /v1, endpoint, API Key, Model ID, перезапуск клиента и типичные ответы 401, 404, 405, HTML, model not found и timeout.

BetterToken

Редакция

16 авг. 2026 г.8 мин чтения

Содержание

Если API Key уже создан, но клиент отвечает 401, 404, 405, model not found, показывает страницу входа или возвращает HTML вместо JSON, не меняйте одновременно ключ, модель и адрес. Сначала разберитесь, что такое Base URL, а затем проверяйте конфигурацию по слоям: протокол → базовый адрес → версия API → endpoint → авторизация → модель.

Base URL (базовый URL) — это корневой адрес API-сервера или API-шлюза. Клиентская библиотека, SDK или CLI добавляет к нему путь конкретного ресурса — endpoint — и получает полный URL запроса.

Ниже BetterToken используется как практический пример. Тот же подход подходит для других API-шлюзов, собственных proxy и сервисов с OpenAI-compatible или Anthropic-compatible протоколом.

Что такое Base URL в API?

Самая простая формула:

Полный URL запроса = Base URL + путь endpoint

Пример OpenAI-compatible запроса:

Base URL:  https://www.bettertoken.ai/v1
Endpoint:  /responses
Полный URL: https://www.bettertoken.ai/v1/responses

Другой распространённый endpoint — /chat/completions:

Base URL:  https://www.bettertoken.ai/v1
Endpoint:  /chat/completions
Полный URL: https://www.bettertoken.ai/v1/chat/completions

На практике клиент обычно сам корректно соединяет части и обрабатывает слэш. Важно не склеивать строку вручную, а проверить, не указан ли в поле Base URL путь, который клиент затем добавит ещё раз.

Из каких частей состоит API URL?

Разберём https://www.bettertoken.ai/v1/responses:

Часть	Пример	Для чего нужна
Протокол	`https://`	Определяет способ сетевого соединения
Домен	`bettertoken.ai`	Указывает на API-сервис
Базовый путь	`/v1`	Выбирает версию API или общий вход
Endpoint	`/responses`	Выбирает конкретный ресурс или операцию

У одних сервисов Base URL содержит только протокол и домен, у других — ещё и путь вроде /v1. Универсального правила «всегда добавлять /v1» нет: значение зависит от сервиса и от клиента.

Что не является Base URL?

Что часто путают	Чем отличается
Главная страница сайта	Она может возвращать HTML; API Base URL предназначен для программных запросов
Полный URL запроса	В нём уже есть endpoint: `/responses`, `/chat/completions` или `/v1/messages`
API Key	Ключ отвечает за авторизацию, а Base URL — за направление запроса
Model ID	Идентификатор выбирает модель, но не определяет протокол и маршрут
Адрес MCP-сервера	MCP подключает инструменты и данные, а не заменяет Base URL model API

Поэтому адрес, который нормально открывается в браузере, не обязательно является правильным Base URL. У рабочего API-корня может не быть читаемой страницы. И наоборот, страница входа может означать, что запрос попал в web-маршрут, а не в API.

Выбирайте адрес по протоколу клиента, а не по названию модели

Один шлюз может одновременно предоставлять OpenAI-compatible и Anthropic-compatible входы. Важнее понять, какой контракт ждёт клиент, чем ориентироваться на название GPT, Claude, Kimi или GLM.

В актуальной документации BetterToken действует такое правило:

Клиент или сценарий	Обычный протокол	Base URL	Что добавляет клиент
Codex	OpenAI Responses	`https://www.bettertoken.ai/v1`	`/responses`
Cursor, Cline, OpenCode и похожие инструменты	OpenAI-compatible	`https://www.bettertoken.ai/v1`	Нужный endpoint, например `/chat/completions`
Claude Code	Anthropic-compatible	`https://bettertoken.ai`	`/v1/messages`
Собственный HTTP-запрос	Зависит от формата запроса	Адрес выбранного протокола	Endpoint указывается в коде

Подробное сравнение есть в материале OpenAI-compatible API и Anthropic-compatible API. Не выбирайте Anthropic Base URL только потому, что хотите вызвать модель Claude. И не выбирайте OpenAI-адрес только по слову GPT: сначала смотрите требования инструмента.

Пять проверок Base URL в правильном порядке

Меняйте по одному параметру и после каждого изменения повторяйте один и тот же короткий запрос. Иначе несколько причин смешаются в одном результате.

1. Определите протокол, который ожидает клиент

Проверьте provider или тип API в самом инструменте:

Codex использует OpenAI Responses.
Cursor, Cline, OpenCode и многие другие инструменты обычно работают через OpenAI-compatible provider.
Claude Code использует Anthropic-compatible Messages.
В собственном скрипте протокол определяется форматом запроса в коде.

При несовместимом протоколе смена модели не исправит проблему: различаться могут поля запроса, авторизация и endpoint.

2. Укажите только базовый адрес, без полного endpoint

Поле base_url, Base URL, API base или endpoint base обычно ожидает общий корень.

Правильно:

https://www.bettertoken.ai/v1

Частые ошибки:

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

Если клиент сам добавляет /responses, первый вариант может превратиться в:

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

Для Claude Code не указывайте https://www.bettertoken.ai/v1/messages в ANTHROPIC_BASE_URL: Claude Code добавляет /v1/messages самостоятельно.

3. Убедитесь, что `/v1` встречается ровно один раз

OpenAI-compatible Base URL BetterToken уже содержит /v1. Если SDK предлагает отдельный параметр api_version, path_prefix или аналогичный, не добавляйте второй /v1, если это прямо не требуется документацией SDK.

Такой адрес в логах почти всегда означает ошибку склейки:

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

Обратная проблема — отсутствие /v1 в OpenAI-compatible запросе. В этом случае возможны 404, HTML вместо JSON или перенаправление на страницу входа.

4. Проверьте endpoint минимальным запросом

Сначала отключите streaming, tools, MCP и длинный контекст. Отправьте через тот же клиент одну короткую фразу. Для первой проверки не используйте рабочий репозиторий с правами на запись.

Запустите Codex:

codex

Введите:

Ответь одной короткой фразой: соединение работает.

Запустите Claude Code:

claude

Введите:

Ответь одной короткой фразой: соединение работает.

Для собственного HTTP-запроса берите Model ID, доступный сейчас в Setup или Model Plaza. В текущей инструкции Codex в качестве примера используется gpt-6-astra, но доступность модели для конкретного ключа нужно проверять в Dashboard. Только после успешного короткого запроса включайте streaming, tools и длинные задачи.

5. Полностью перезапустите клиент

Многие CLI, desktop-приложения и расширения редакторов читают переменные окружения и конфигурацию только при запуске. Сохранённый файл ещё не означает, что работающий процесс получил новое значение.

После изменения:

Закройте CLI, приложение или окно редактора.
Убедитесь, что связанные фоновые процессы завершены.
Откройте новый терминал или заново запустите приложение.
Повторите тот же короткий запрос.

Иначе в редакторе вы видите новый Base URL, а фактически проверяете старый.

Как читать типичные ответы

Симптом	Что проверить первым	Следующее действие
`404 Not Found`	Двойной `/v1`, повторный endpoint, несовпадение протокола	Сравните фактический request URL в логах с документацией
HTML или страница входа	Не попал ли запрос в web-маршрут вместо API	Проверьте домен, `/v1` и endpoint
`401`	API Key, переменную авторизации и активную конфигурацию	Уберите лишние пробелы в ключе и перезапустите клиент
`403`	Доступен ли выбранный маршрут или модель для ключа	Проверьте доступность модели в Setup или Dashboard
`405 Method Not Allowed`	HTTP method и endpoint	Убедитесь, что маршрут ожидает `POST` или другой нужный метод
`model not found`	Сначала Base URL и протокол, затем Model ID	Не маскируйте ошибку маршрута заменой модели
timeout или обрыв stream	Короткий запрос без streaming	Если он проходит, отдельно проверяйте streaming и timeout
Изменения не применились	Путь файла, переопределяющие переменные, фоновые процессы	Полностью закройте и запустите заново

401 не доказывает, что адрес верный, а 404 не доказывает отсутствие модели. Код статуса описывает реакцию сервера на полученный запрос, но не заменяет проверку полного request URL.

Быстрая проверка конфигурации Codex и Claude Code

Codex

Фрагмент Codex, связанный с адресом, должен выглядеть примерно так:

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

API Key хранится в auth.json в том же каталоге конфигурации Codex. Полную схему и правила авторизации смотрите в инструкции Codex. Codex сам добавляет /responses, поэтому не включайте этот endpoint в base_url.

Claude Code

Основные переменные адреса и авторизации:

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

Этот фрагмент показывает только Base URL и token. Полный рекомендуемый набор параметров приведён в инструкции Claude Code. Не добавляйте к ANTHROPIC_BASE_URL ни /v1, ни /messages.

Четыре типичные ошибки склейки

Ошибка:  https://www.bettertoken.ai/v1/v1/responses
Причина: Base URL и клиент оба добавили /v1

Ошибка:  https://www.bettertoken.ai/v1/responses/responses
Причина: полный endpoint был указан как Base URL

Ошибка:  Base URL Claude Code = https://www.bettertoken.ai/v1/messages
Причина: Claude Code снова добавит /v1/messages

Ошибка:  OpenAI-compatible клиент использует https://bettertoken.ai
Причина: отсутствует обязательный для этого входа путь /v1

Сначала исправьте путь, и только потом меняйте ключ, модель или расширенные настройки.

Что не стоит делать

Не меняйте Base URL, API Key и Model ID одновременно.
Не копируйте один Base URL во все инструменты.
Не определяйте протокол по названию модели.
Не берите адрес из старого скриншота или гайда без сверки с текущей документацией.
Не используйте реальный проект с правами на запись для первого теста.
Не публикуйте полный API Key в issue, переписке или скриншоте.
Не настраивайте streaming, tools, MCP и timeout, пока не работает базовый запрос.

Частые вопросы

Что такое Base URL?

Base URL — это корневой адрес API-сервера или шлюза. Клиент добавляет к нему конкретный endpoint, например /responses, /chat/completions или /v1/messages.

Чем Base URL отличается от endpoint?

Base URL — общий корень для множества запросов. Endpoint — путь конкретного ресурса или операции. Вместе они образуют полный URL запроса.

Почему неправильный Base URL часто возвращает 404?

Обычно причина в повторном /v1, двойном endpoint, пропущенном базовом пути или несовпадении OpenAI-compatible и Anthropic-compatible протоколов.

Во всех ли Base URL BetterToken нужен `/v1`?

Нет. Codex, Cursor, Cline и другие OpenAI-compatible клиенты обычно используют https://www.bettertoken.ai/v1. Claude Code использует https://bettertoken.ai и сам добавляет /v1/messages.

Почему изменение Base URL не применилось?

Работающий процесс мог сохранить старые переменные окружения или конфигурацию. Полностью завершите клиент и фоновые процессы, затем откройте новый терминал или перезапустите приложение.

Base URL и MCP — это одно и то же?

Нет. Base URL и API Key отвечают за маршрутизацию и авторизацию запросов к модели. MCP подключает внешние инструменты, файлы, базы данных и другой контекст. Подробнее: MCP и API Key / Base URL.

Следующий шаг

Откройте документацию BetterToken, выберите свой инструмент и скопируйте только актуальный Base URL с его страницы. Отправьте короткий запрос со своим API Key без streaming и tools, затем проверьте в Dashboard время, статус, модель и расход токенов.

После успешного базового запроса возвращайте переключение моделей, длинный контекст, tools, MCP и streaming по одному слою. Так вопрос «правильно ли указан адрес?» не смешивается с вопросом «работает ли расширенная функция?», и поиск ошибки занимает намного меньше времени.