Base URL이란? API 설정과 401·404 오류 해결

API Key를 이미 만들었는데도 클라이언트가 401, 404, 405, model not found를 반환하거나, 로그인 페이지를 열거나, JSON 대신 HTML을 받는다면 Key·모델·주소를 한꺼번에 바꾸지 마세요. 먼저 Base URL이 무엇인지 확인한 다음 프로토콜 → 기준 주소 → API 버전 → endpoint → 인증 → 모델 순서로 설정을 점검하는 편이 가장 빠릅니다.

Base URL은 API 서버 또는 API 게이트웨이의 기준이 되는 루트 주소입니다. 클라이언트 라이브러리, SDK, CLI가 특정 리소스의 경로인 endpoint를 여기에 붙여 전체 요청 URL을 만듭니다.

아래에서는 BetterToken을 예로 들지만, 같은 원리는 다른 API 게이트웨이, 자체 구축 프록시, OpenAI-compatible 또는 Anthropic-compatible 서비스에도 적용됩니다.

API에서 Base URL이란 무엇인가요?

가장 간단한 공식은 다음과 같습니다.

전체 요청 URL = Base URL + Endpoint Path

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 같은 베이스 경로까지 포함합니다. 모든 API에 적용되는 공통 suffix는 없습니다. 현재 서비스와 클라이언트 문서를 기준으로 판단해야 합니다.

Base URL이 아닌 것

혼동하기 쉬운 개념	Base URL과의 차이
웹사이트 홈	HTML을 반환할 수 있으며, API Base URL은 프로그램 요청용입니다
전체 요청 URL	`/responses`, `/chat/completions`, `/v1/messages` 같은 endpoint가 이미 들어 있습니다
API Key	Key는 인증을 담당하고, Base URL은 요청 목적지를 결정합니다
Model ID	호출할 모델을 선택하지만 프로토콜이나 경로를 결정하지 않습니다
MCP 서버 주소	MCP는 도구와 데이터 소스를 연결하며 모델 API Base URL을 대신하지 않습니다

따라서 브라우저에서 주소가 열린다고 해서 올바른 Base URL이라는 뜻은 아닙니다. 정상적인 API 루트가 읽을 수 있는 페이지를 보여 주지 않을 수도 있습니다. 반대로 정상적으로 보이는 로그인 페이지가 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`	`/chat/completions` 등 필요한 endpoint
Claude Code	Anthropic-compatible	`https://bettertoken.ai`	`/v1/messages`
직접 작성한 HTTP 요청	요청 형식에 따라 다름	선택한 프로토콜의 주소	코드에서 endpoint를 명시

자세한 차이는 OpenAI-compatible API와 Anthropic-compatible API에서 확인할 수 있습니다. Claude 모델을 사용한다는 이유만으로 모든 도구에 Anthropic 주소를 넣지 마세요. GPT 모델을 사용하더라도 클라이언트가 요구하는 프로토콜을 무시할 수 없습니다.

Base URL을 확인하는 5단계

한 번에 하나의 설정만 바꾸고, 변경할 때마다 같은 짧은 요청을 반복하세요. 그래야 어느 계층에서 문제가 해결되었는지 알 수 있습니다.

1. 클라이언트가 요구하는 프로토콜을 확인합니다

도구 안의 provider 또는 API type을 확인하세요.

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의 ANTHROPIC_BASE_URL에도 https://www.bettertoken.ai/v1/messages를 넣지 마세요. Claude Code가 /v1/messages를 직접 붙입니다.

3. `/v1`이 정확히 한 번만 있는지 확인합니다

OpenAI-compatible 클라이언트용 BetterToken Base URL에는 이미 /v1이 들어 있습니다. SDK에 api_version, path_prefix 같은 별도 설정이 있더라도, 해당 SDK 문서가 명시적으로 요구하지 않는 한 두 번째 /v1을 추가하지 마세요.

로그에서 다음 URL이 보이면 대부분 경로 결합 오류입니다.

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

반대로 OpenAI-compatible 요청에 /v1이 전혀 없으면 404, JSON 대신 HTML, 로그인 페이지로의 리디렉션이 발생할 수 있습니다.

4. 가장 작은 요청으로 endpoint를 테스트합니다

streaming, tools, MCP, 긴 컨텍스트를 끄고 같은 클라이언트에서 짧은 문장 하나만 보냅니다. 첫 연결 테스트부터 실제 저장소에서 쓰기 작업을 실행하지 마세요.

Codex를 실행합니다.

codex

다음과 같이 입력합니다.

짧은 한 문장으로만 답하세요: 연결에 성공했습니다.

Claude Code를 실행합니다.

claude

다음과 같이 입력합니다.

짧은 한 문장으로만 답하세요: 연결에 성공했습니다.

직접 HTTP 요청을 보낸다면 Setup 또는 Model Plaza에서 현재 사용할 수 있는 Model ID를 사용하세요. 현행 Codex 문서는 gpt-6-astra를 예시로 사용하지만, 해당 Key로 실제 사용 가능한 모델은 Dashboard를 기준으로 해야 합니다. 최소 요청이 성공한 뒤에 streaming, tools, 긴 작업을 다시 켜세요.

5. 클라이언트를 완전히 재시작합니다

많은 CLI, 데스크톱 앱, 에디터 확장은 시작할 때만 환경 변수와 설정 파일을 읽습니다. 파일을 저장했다고 실행 중인 프로세스가 새 값을 읽은 것은 아닙니다.

변경 후에는 다음 순서로 진행하세요.

CLI, 데스크톱 앱, 에디터 창을 닫습니다.
관련 백그라운드 프로세스까지 종료되었는지 확인합니다.
새 터미널을 열거나 앱을 다시 실행합니다.
같은 짧은 테스트 요청을 반복합니다.

그렇지 않으면 화면에서는 새 설정을 보고 있으면서 실제로는 이전 Base URL을 테스트할 수 있습니다.

자주 발생하는 오류를 해석하는 방법

증상	먼저 확인할 항목	다음 조치
`404 Not Found`	`/v1` 중복, endpoint 중복, 프로토콜 불일치	로그의 실제 request URL과 문서를 비교
HTML 또는 로그인 페이지	API가 아닌 웹 경로를 호출했는지	호스트, `/v1`, endpoint 확인
`401`	API Key, 인증 변수, 현재 활성 설정	Key 앞뒤 공백을 제거하고 재시작
`403`	Key가 선택한 모델이나 경로에 접근 가능한지	Setup 또는 Dashboard에서 확인
`405 Method Not Allowed`	HTTP method와 endpoint	`POST` 등 요구되는 method 확인
`model not found`	Model ID보다 Base URL과 프로토콜을 먼저 확인	모델 변경으로 라우팅 오류를 숨기지 않기
timeout 또는 stream 중단	streaming 없는 짧은 요청	성공한다면 streaming과 timeout을 따로 확인
수정 후 변화 없음	설정 파일 위치, 환경 변수 덮어쓰기, 실행 프로세스	완전히 종료한 뒤 재실행

401이 나온다고 URL이 맞는 것은 아니며, 404가 나온다고 모델이 없는 것도 아닙니다. 상태 코드는 서버가 받은 요청을 어떻게 처리했는지만 보여 줍니다.

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는 같은 Codex 설정 디렉터리의 auth.json에 저장합니다. 전체 필드와 인증 규칙은 Codex 설정 문서를 따르세요. Codex가 /responses를 붙이므로 base_url에 넣지 않습니다.

Claude Code

주소와 인증에 필요한 핵심 변수는 다음과 같습니다.

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

이 예시는 주소와 인증 변수만 강조한 것입니다. 전체 권장 설정은 Claude Code 문서를 확인하세요. ANTHROPIC_BASE_URL 뒤에 /v1이나 /messages를 붙이지 마세요.

URL 결합에서 흔한 4가지 오류

오류: https://www.bettertoken.ai/v1/v1/responses
원인: Base URL과 클라이언트가 모두 /v1을 붙임

오류: https://www.bettertoken.ai/v1/responses/responses
원인: 전체 endpoint를 Base URL로 입력함

오류: Claude Code Base URL = https://www.bettertoken.ai/v1/messages
원인: Claude Code가 /v1/messages를 다시 붙임

오류: OpenAI-compatible 클라이언트가 https://bettertoken.ai 사용
원인: 이 진입점에 필요한 /v1 베이스 경로가 없음

Key, 모델, 고급 파라미터를 바꾸기 전에 먼저 경로 결합을 고치세요.

피해야 할 문제 해결 방식

Base URL, API Key, Model ID를 동시에 바꾸지 마세요.
같은 Base URL을 모든 도구에 복사하지 마세요.
모델 이름만 보고 프로토콜을 추정하지 마세요.
오래된 스크린샷이나 가이드의 주소를 최신 문서 확인 없이 사용하지 마세요.
첫 연결 테스트에 쓰기 권한이 있는 실제 프로젝트를 사용하지 마세요.
전체 API Key를 issue, 채팅, 스크린샷에 공개하지 마세요.
기본 요청이 성공하기 전에 streaming, tools, MCP, timeout을 조정하지 마세요.

자주 묻는 질문

Base URL이란 무엇인가요?

API 서버 또는 게이트웨이의 기준 주소입니다. 클라이언트가 /responses, /chat/completions, /v1/messages 같은 endpoint를 붙입니다.

Base URL과 endpoint는 어떻게 다른가요?

Base URL은 여러 요청이 공유하는 루트 주소입니다. endpoint는 특정 리소스나 작업의 경로입니다. 두 값을 합치면 전체 요청 URL이 됩니다.

잘못된 Base URL에서 404가 자주 발생하는 이유는 무엇인가요?

/v1 중복, endpoint 중복, 필수 베이스 경로 누락, OpenAI-compatible 클라이언트와 Anthropic-compatible 주소의 불일치가 대표적인 원인입니다.

BetterToken Base URL에는 모두 `/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에서 요청 시간, 상태, 모델, token 사용량을 확인합니다.

기본 요청이 성공한 다음 모델 전환, 긴 컨텍스트, tools, MCP, streaming을 하나씩 다시 켜세요. “주소가 맞는가?”와 “고급 기능이 작동하는가?”를 분리하면 원인을 훨씬 빠르게 찾을 수 있습니다.

초대 보상 안내

Base URL이란? API 주소 구조와 401·404 오류 해결 방법

API에서 Base URL이란 무엇인가요?

API URL의 구성 요소

Base URL이 아닌 것

모델 이름이 아니라 클라이언트 프로토콜로 주소를 선택하세요

Base URL을 확인하는 5단계

1. 클라이언트가 요구하는 프로토콜을 확인합니다

2. 전체 endpoint가 아니라 기준 주소만 입력합니다

3. `/v1`이 정확히 한 번만 있는지 확인합니다

4. 가장 작은 요청으로 endpoint를 테스트합니다

5. 클라이언트를 완전히 재시작합니다

자주 발생하는 오류를 해석하는 방법

Codex와 Claude Code 빠른 설정 확인

Codex

Claude Code

URL 결합에서 흔한 4가지 오류

피해야 할 문제 해결 방식

자주 묻는 질문

Base URL이란 무엇인가요?

Base URL과 endpoint는 어떻게 다른가요?

잘못된 Base URL에서 404가 자주 발생하는 이유는 무엇인가요?

BetterToken Base URL에는 모두 `/v1`이 필요한가요?

Base URL을 바꿨는데 왜 적용되지 않나요?

Base URL과 MCP는 같은 것인가요?

다음 단계

LLM 워크플로를 최적화할 준비가 되셨나요?

API에서 Base URL이란 무엇인가요?

API URL의 구성 요소

Base URL이 아닌 것

모델 이름이 아니라 클라이언트 프로토콜로 주소를 선택하세요

Base URL을 확인하는 5단계

1. 클라이언트가 요구하는 프로토콜을 확인합니다

2. 전체 endpoint가 아니라 기준 주소만 입력합니다

3. /v1이 정확히 한 번만 있는지 확인합니다

4. 가장 작은 요청으로 endpoint를 테스트합니다

5. 클라이언트를 완전히 재시작합니다

자주 발생하는 오류를 해석하는 방법

Codex와 Claude Code 빠른 설정 확인

Codex

Claude Code

URL 결합에서 흔한 4가지 오류

피해야 할 문제 해결 방식

자주 묻는 질문

Base URL이란 무엇인가요?

Base URL과 endpoint는 어떻게 다른가요?

잘못된 Base URL에서 404가 자주 발생하는 이유는 무엇인가요?

BetterToken Base URL에는 모두 /v1이 필요한가요?

Base URL을 바꿨는데 왜 적용되지 않나요?

Base URL과 MCP는 같은 것인가요?

다음 단계

모든 글

LLM 워크플로를 최적화할 준비가 되셨나요?

3. `/v1`이 정확히 한 번만 있는지 확인합니다

BetterToken Base URL에는 모두 `/v1`이 필요한가요?