Base URL 오류: protocol, path, endpoint 확인 방법
Base URL을 점검하는 실전 순서입니다. protocol, domain, API version, endpoint, client 설정을 확인하고 변경할 때마다 짧은 test request를 실행합니다.
API Key를 만들었는데도 client가 401, 404, 405, model not found를 반환하거나 login page를 연다면 key, model, address를 한 번에 바꾸지 마세요. 먼저 client가 OpenAI-compatible contract와 Anthropic-compatible contract 중 무엇을 기대하는지 확인합니다. 그다음 https → domain → base path → endpoint 순서로 address를 검사하고, 변경할 때마다 같은 짧은 request를 보냅니다. 이렇게 하면 configuration이 어느 layer에서 contract와 달라졌는지 알 수 있습니다.
BetterToken에서는 이 차이가 특히 중요합니다. OpenAI-compatible client의 Base URL은 https://www.bettertoken.ai/v1%60%EC%9D%B4%EA%B3%A0,?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-022&utm_content=base-url-oshibka-kak-proverit-put-i-protokol Claude Code의 Anthropic-compatible Base URL은 https://bettertoken.ai`이며 필요한 path는 Claude Code가 추가합니다. 두 값은 같은 string의 변형이 아니며 서로 바꿔 쓸 수 없습니다. 사용하는 tool의 최신 값은 BetterToken Docs에서 확인하세요.
Base URL과 전체 request URL을 구분하기
Base URL은 provider field나 client config에 입력하는 address입니다. 전체 request URL은 library나 CLI가 resource path를 더해 만들게 됩니다.
raw Anthropic Messages request를 직접 작성할 때 전체 path는 https://www.bettertoken.ai/v1/messages%60%EC%9E%85%EB%8B%88%EB%8B%A4.?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-022&utm_content=base-url-oshibka-kak-proverit-put-i-protokol 그러나 이것은 Claude Code의 Base URL field 값이 아닙니다. OpenAI-compatible client에서 base address는 보통 /v1`으로 끝나며 endpoint는 client가 추가합니다. 이 구분은 Claude Code guide와 Codex guide에 있습니다.
올바른 순서의 다섯 가지 점검
각 단계 뒤에 같은 짧은 request를 반복하세요. 하나의 response에 여러 원인을 섞지 않기 위해서입니다.
- client가 기대하는 protocol을 결정합니다.
- endpoint 없이 알맞은 Base URL만 입력합니다.
- request URL에
/v1이 정확히 한 번 있는지 봅니다. - streaming과 tools 없이 minimal request를 실행합니다.
- client를 완전히 restart한 뒤 같은 test를 반복합니다.
1. model 이름이 아니라 protocol 확인
tool의 integration type을 확인하세요. Codex, Cursor, Cline, OpenCode 등 많은 tool은 OpenAI-compatible setting을 사용합니다. Claude Code는 Anthropic-compatible contract를 사용합니다. 다른 contract를 보내는 경우 model을 바꿔도 해결되지 않습니다. client와 server가 요구하는 fields와 paths가 다르기 때문입니다. model 이름으로 추측하지 말고 해당 tool의 Docs에서 provider, API Key, Base URL section을 찾으세요.
2. Base URL에서 불필요한 path 제거
OpenAI-compatible setup에는 다음을 사용합니다.
Claude Code에는 /v1과 /messages 없이 다음을 사용합니다.
자주 생기는 문제는 curl example의 전체 URL을 GUI Base URL field에 붙여넣는 것입니다. client가 자신의 endpoint를 다시 추가하므로 존재하지 않는 route가 됩니다. field 이름이 base_url, endpoint base, API base라면 일반적으로 resource name을 넣지 않습니다.
3. /v1을 누가 담당하는지 확인
API version은 정확히 한 번만 나타나야 합니다. BetterToken OpenAI-compatible setting에서는 /v1이 이미 Base URL에 포함됩니다. SDK가 version prefix를 따로 설정할 수 있어도 SDK Docs의 명시적인 지시 없이 두 번째 /v1을 추가하지 마세요. log의 .../v1/v1/...는 거의 항상 join error입니다. 반대로 OpenAI-compatible request에 /v1이 없으면 404 또는 JSON 대신 HTML이 나올 수 있습니다.
4. minimal request로 endpoint 확인
streaming, tools, 긴 context를 켜기 전에 같은 client에서 짧은 request를 하나 보냅니다. raw OpenAI-compatible request의 endpoint는 Base URL 뒤의 resource이고, Anthropic Messages는 /v1/messages입니다. Setup panel이나 model plaza의 current Model ID와 본인 API Key를 사용하세요. key를 issue, screenshot, 공유할 command에 넣으면 안 됩니다. success JSON, model, usage가 돌아오면 address layer는 통과한 것입니다. 그 뒤에 limits, model, task parameters를 확인하세요.
5. 변경 후 client 완전 restart
많은 CLI와 desktop app은 environment variables와 config를 startup 때만 읽습니다. file을 저장하는 것만으로는 부족합니다. process를 종료하고 새 terminal을 열거나 app을 restart한 후 같은 짧은 test를 반복하세요. 그렇지 않으면 editor에는 새 Base URL이 보여도 test는 이전 값을 사용합니다.
자주 보는 response 읽는 법
401이 항상 address 오류는 아니고 404가 항상 model 부재도 아닙니다. URL, authentication, model, advanced features 순서로 확인하는 것이 중요한 이유입니다.
Codex와 Claude Code 빠른 점검
Codex에서는 OpenAI-compatible provider와 current Codex instructions를 사용합니다. Base URL `https://www.bettertoken.ai/v1%60,?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-022&utm_content=base-url-oshibka-kak-proverit-put-i-protokol 본인의 BetterToken API Key, current Model ID를 설정하세요. Codex를 restart하고 test directory에서 작은 read-only request를 실행합니다. Dashboard에서는 request time, status, model, token usage를 확인할 수 있습니다.
Claude Code에서는 Claude Code instructions를 사용합니다. Anthropic-compatible Base URL은 https://bettertoken.ai이며 자신의 key와 guide에 적힌 model을 설정합니다. 이 field에 OpenAI /v1을 넣거나 /messages를 직접 추가하지 마세요. restart 후 짧은 request를 실행하고 tools 또는 MCP는 그다음에 추가합니다.
피해야 할 것
- Base URL, API Key, Model ID를 한 번에 바꾸지 마세요.
- 모든 tool에 같은 address를 넣지 마세요. protocol은 client가 결정합니다.
- 날짜와 tool page를 확인하지 않은 오래된 guide의 path를 사용하지 마세요.
- 첫 test를 write access가 있는 실제 repository에서 실행하지 마세요. 빈 test folder와 read-only task를 사용하세요.
- 전체 API Key를 support에 보내지 마세요. status, time, tool name, sanitized request URL이면 충분합니다.
다음 단계
사용 중인 tool의 BetterToken Docs를 열고 BetterToken account에서 본인의 API Key를 만든 뒤 선택한 protocol의 current Base URL을 복사해 짧은 test를 실행하세요. 성공하면 Dashboard의 status, model, token usage를 대조하세요. 설정이 저장되었다는 사실만 확인하는 것보다 신뢰할 수 있습니다。