त्रुटियाँ और विश्वसनीयता

Base URL क्या है? API संरचना, सही प्रोटोकॉल और 401/404 त्रुटियों का समाधान

Base URL किसी API सर्वर या gateway का मूल पता होता है। क्लाइंट इसमें किसी खास endpoint का path जोड़कर पूरा request URL बनाता है। यह मार्गदर्शिका Base URL, endpoint और full URL का अंतर समझाती है, OpenAI-compatible क्लाइंट और Claude Code के लिए सही BetterToken पता चुनने का तरीका बताती है, और 401, 404, 405, model not found, HTML response, timeout तथा पुरानी configuration लागू रहने जैसी समस्याओं को क्रम से जाँचने में मदद करती है।

BetterToken

संपादकीय टीम

16 अग॰ 20269 मिनट पढ़ने में

विषय-सूची

यदि API Key बन चुकी है, फिर भी client 401, 404, 405, model not found दिखाता है, login page खोल देता है, या JSON की जगह HTML लौटाता है, तो एक साथ Key, model और address न बदलें। पहले समझें कि Base URL क्या है, फिर configuration को इस क्रम में जाँचें: protocol → root address → API version path → endpoint → authentication → model।

Base URL किसी API server या API gateway का मूल पता होता है। Client library, SDK या command-line tool इसमें किसी खास resource का path—यानी endpoint—जोड़ता है और पूरा request URL बनाता है।

नीचे BetterToken को उदाहरण के रूप में इस्तेमाल किया गया है। यही तरीका दूसरे API gateways, self-hosted proxies और OpenAI-compatible या Anthropic-compatible services पर भी लागू होता है।

API में Base URL क्या होता है?

सबसे सरल सूत्र है:

पूरा request URL = Base URL + Endpoint Path

OpenAI-compatible request का उदाहरण:

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

एक दूसरा सामान्य endpoint /chat/completions है:

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

असल application में client आम तौर पर दोनों हिस्सों के बीच slash को स्वयं संभालता है। मुख्य सवाल यह नहीं है कि strings को हाथ से कैसे जोड़ा जाए। मुख्य सवाल यह है कि Base URL field में कहीं ऐसा path पहले से तो नहीं है जिसे client दोबारा जोड़ देगा।

API URL किन हिस्सों से बनता है?

https://www.bettertoken.ai/v1/responses को देखें:

हिस्सा	उदाहरण	काम
Scheme	`https://`	Network connection का तरीका तय करता है
Host	`bettertoken.ai`	API service का domain बताता है
Base path	`/v1`	API version या common entry point चुनता है
Endpoint	`/responses`	किसी खास resource या operation को चुनता है

कुछ services में Base URL केवल scheme और host होता है। कुछ में /v1 जैसा base path भी शामिल होता है। हर जगह एक ही suffix लागू नहीं होता; service और client की मौजूदा documentation देखें।

Base URL किन चीजों के बराबर नहीं है?

अक्सर किससे भ्रम होता है	अंतर
Website home page	Home page HTML दे सकता है; API Base URL programmatic requests के लिए होता है
पूरा request URL	इसमें `/responses`, `/chat/completions` या `/v1/messages` जैसा endpoint पहले से होता है
API Key	Key request को authenticate करती है; Base URL तय करता है कि request कहाँ जाएगी
Model ID	Model ID model चुनता है; protocol या route नहीं
MCP server address	MCP tools और data sources जोड़ता है; यह model API Base URL नहीं है

इसलिए browser में कोई URL खुल जाना इस बात का प्रमाण नहीं है कि वह सही Base URL है। कई valid API roots readable page नहीं दिखाते। दूसरी ओर, खुलने वाला login page website route हो सकता है, API route नहीं।

Model के नाम से नहीं, client protocol से address चुनें

एक ही model gateway OpenAI-compatible और Anthropic-compatible दोनों entry points दे सकता है। Client किस protocol की अपेक्षा करता है, यह GPT, Claude, Kimi या GLM जैसे model नाम से अधिक महत्वपूर्ण है।

BetterToken की मौजूदा documentation के अनुसार:

Client या scenario	सामान्य protocol	भरने वाला Base URL	Client द्वारा जोड़ा गया path
Codex	OpenAI Responses	`https://www.bettertoken.ai/v1`	`/responses`
Cursor, Cline, OpenCode आदि	OpenAI-compatible	`https://www.bettertoken.ai/v1`	Client के अनुसार, जैसे `/chat/completions`
Claude Code	Anthropic-compatible	`https://bettertoken.ai`	`/v1/messages`
आपका raw HTTP request	Request format पर निर्भर	उसी protocol का address	Endpoint code में स्पष्ट लिखा जाता है

अंतर समझने के लिए OpenAI-compatible और Anthropic-compatible API देखें। केवल Claude model चलाने के कारण हर tool में Anthropic address न भरें। इसी तरह GPT model के नाम से client की वास्तविक protocol requirement को नज़रअंदाज़ न करें।

Base URL जाँचने के पाँच चरण

एक बार में केवल एक setting बदलें और हर बदलाव के बाद वही छोटा request दोहराएँ। इससे पता चलता है कि समस्या किस layer में थी।

1. Client का अपेक्षित protocol पहचानें

Tool के provider या API type को देखें:

Codex OpenAI Responses इस्तेमाल करता है।
Cursor, Cline, OpenCode और कई दूसरे tools सामान्यतः OpenAI-compatible provider इस्तेमाल करते हैं।
Claude Code Anthropic-compatible Messages protocol इस्तेमाल करता है।
Custom script में protocol code के request format से तय होता है।

Protocol mismatch होने पर model बदलना समाधान नहीं है। Request fields, authentication conventions और endpoint paths अलग हो सकते हैं।

2. केवल root address भरें, पूरा endpoint नहीं

base_url, Base URL, API base या endpoint base नाम का field सामान्यतः साझा root चाहता है।

सही:

https://www.bettertoken.ai/v1

आम गलतियाँ:

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

यदि client /responses स्वयं जोड़ता है, तो पहला गलत address बन सकता है:

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 clients के लिए BetterToken Base URL में /v1 पहले से है। यदि SDK में अलग api_version, path_prefix या ऐसा कोई field है, तो दूसरा /v1 तभी जोड़ें जब SDK की documentation स्पष्ट रूप से कहे।

Log में यह URL लगभग हमेशा joining error दिखाता है:

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

दूसरी ओर, OpenAI-compatible request में /v1 बिल्कुल न होने पर 404, JSON की जगह HTML, या login page की ओर redirect मिल सकता है।

4. सबसे छोटे request से endpoint जाँचें

Streaming, tools, MCP और long context बंद करें। उसी client से केवल एक छोटा prompt भेजें। पहले test के लिए वास्तविक repository में write-enabled task न चलाएँ।

Codex शुरू करें:

codex

फिर लिखें:

केवल एक छोटे वाक्य में उत्तर दें: कनेक्शन सफल है।

Claude Code शुरू करें:

claude

फिर लिखें:

केवल एक छोटे वाक्य में उत्तर दें: कनेक्शन सफल है।

Raw HTTP request में Setup या Model Plaza में वर्तमान रूप से उपलब्ध Model ID इस्तेमाल करें। मौजूदा Codex guide में gpt-6-astra उदाहरण है, लेकिन आपके key के लिए उपलब्ध model dashboard से ही तय करें। छोटा request सफल होने के बाद ही streaming, tools या लंबा task वापस चालू करें।

5. Client को पूरी तरह restart करें

कई CLI, desktop applications और editor extensions environment variables तथा configuration files केवल startup पर पढ़ते हैं। File save होने का अर्थ यह नहीं कि चल रहा process नई value पढ़ चुका है।

बदलाव के बाद:

CLI, desktop app या editor window बंद करें।
संबंधित background processes भी समाप्त हों, यह जाँचें।
नया terminal खोलें या application दोबारा शुरू करें।
वही छोटा test request फिर चलाएँ।

वरना editor में नया Base URL दिखेगा, लेकिन process पुराना address इस्तेमाल कर रहा होगा।

सामान्य errors को कैसे समझें

लक्षण	पहले क्या जाँचें	अगला कदम
`404 Not Found`	Duplicate `/v1`, duplicate endpoint, protocol mismatch	Logs में actual request URL को documentation से मिलाएँ
HTML या login page	Website route तो नहीं खुला	Host, `/v1` और endpoint जाँचें
`401`	API Key, auth variable, active configuration	Key के आसपास spaces हटाएँ और client restart करें
`403`	Key को selected model या route का access है या नहीं	Setup या dashboard में model availability देखें
`405 Method Not Allowed`	HTTP method और endpoint	Route `POST` चाहता है या कोई दूसरा method, जाँचें
`model not found`	पहले Base URL और protocol, फिर Model ID	Routing error को model बदलकर न छिपाएँ
Timeout या stream टूटना	छोटा non-streaming request	वह सफल हो तो streaming और timeout अलग जाँचें
Edit के बाद कोई फर्क नहीं	File path, environment overrides, background process	पूरी तरह quit करके restart करें

401 इस बात का प्रमाण नहीं कि URL सही है, और 404 यह साबित नहीं करता कि model गायब है। Status code केवल बताता है कि server ने मिले हुए request पर कैसे प्रतिक्रिया दी।

Codex और Claude Code की त्वरित configuration जाँच

Codex

Codex configuration में address से संबंधित भाग ऐसा दिखना चाहिए:

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 configuration directory के auth.json में रहती है। सभी fields और authentication rules के लिए Codex configuration guide देखें। Codex /responses स्वयं जोड़ता है, इसलिए इसे base_url में न लिखें।

Claude Code

Claude Code के address variables:

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

यह fragment केवल address और authentication variables दिखाता है। पूरी recommended configuration के लिए Claude Code guide देखें। ANTHROPIC_BASE_URL के अंत में /v1 या /messages न जोड़ें।

URL जोड़ते समय होने वाली चार सामान्य गलतियाँ

गलत:   https://www.bettertoken.ai/v1/v1/responses
कारण:  Base URL और client दोनों ने /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 client https://bettertoken.ai इस्तेमाल करता है
कारण:  इस entry point के लिए जरूरी /v1 path गायब है

Key, model या advanced parameters बदलने से पहले इन paths को सही करें।

क्या न करें

Base URL, API Key और Model ID एक साथ न बदलें।
एक ही Base URL हर tool में copy न करें।
Model name से protocol का अनुमान न लगाएँ।
पुरानी screenshot या guide से address लेकर current documentation की जाँच छोड़े नहीं।
पहले connection test के लिए write access वाली वास्तविक project repository इस्तेमाल न करें।
पूरा API Key issue, chat या screenshot में साझा न करें।
Basic request सफल होने से पहले streaming, tools, MCP या timeout tune न करें।

अक्सर पूछे जाने वाले सवाल

Base URL क्या है?

Base URL किसी API server या gateway का मूल पता है। Client इसमें /responses, /chat/completions या /v1/messages जैसा endpoint जोड़ता है।

Base URL और endpoint में क्या अंतर है?

Base URL कई requests का साझा root है। Endpoint किसी खास resource या operation का path है। दोनों मिलकर पूरा request URL बनाते हैं।

गलत Base URL से अक्सर 404 क्यों मिलता है?

सामान्य कारण duplicate /v1, duplicate endpoint, missing base path, या OpenAI-compatible client और Anthropic-compatible address का mismatch है।

क्या BetterToken के सभी Base URL में `/v1` चाहिए?

नहीं। Codex, Cursor और Cline जैसे OpenAI-compatible clients सामान्यतः https://www.bettertoken.ai/v1 इस्तेमाल करते हैं। Claude Code https://bettertoken.ai इस्तेमाल करता है और /v1/messages स्वयं जोड़ता है।

Base URL बदलने के बाद बदलाव लागू क्यों नहीं हुआ?

चल रहा process पुराने environment variables या cached configuration का इस्तेमाल कर सकता है। Client और background processes को पूरी तरह बंद करें, फिर नया terminal या application शुरू करें।

क्या Base URL और MCP एक ही हैं?

नहीं। Base URL और API Key model request routing तथा authentication configure करते हैं। MCP external tools, files, databases और दूसरे context जोड़ता है। अधिक जानकारी के लिए MCP बनाम API Key और Base URL देखें।

अगला कदम

BetterToken documentation खोलें, अपने वास्तविक tool का page चुनें और उसी page पर दिया गया current Base URL copy करें। अपने API Key से एक छोटा request भेजें, streaming और tools बंद रखें, फिर Dashboard में request time, status, model और token usage जाँचें।

Basic request सफल होने के बाद model switching, long context, tools, MCP और streaming को एक-एक layer करके वापस चालू करें। इससे “address सही है या नहीं” और “advanced feature काम कर रहा है या नहीं” अलग-अलग जाँचे जा सकते हैं।