OpenAI-Compatible Base URL Troubleshooting: 7 Checks Before You Blame the SDK

An OpenAI-compatible base URL is supposed to make model switching boring: change the endpoint, keep the SDK, and move on. In real projects, the first run often fails with a 401 , 404 , 429 , or a model-not-found error. Here is the checklist I use before blaming the SDK. 1. Confirm the base URL includes the right API prefix Most OpenAI-compatible gateways expect a /v1 prefix: from openai import OpenAI client = OpenAI ( api_key = " YOUR_RELAY_KEY " , base_url = " https://api.wappkit.com/v1 " , ) If you use only the domain, some SDK calls may resolve to the wrong path. Check the provider's docs and copy the exact base URL format. 2. Make sure the key belongs to that gateway A common mistake is mixing keys: OpenAI key with relay base URL Relay key with OpenAI base URL Old test key from a disabled project Key copied with a leading or trailing space When you see 401 Unauthorized , print the first and last few characters of the key locally and compare it with the dashboard. Do not log the full key. 3. Check the model name from the live list Do not guess model names from memory. Gateway model names can change as upstream availability changes. Before using gpt-5.5 , gpt-5.4 , or a Claude Code model, check the current model list . Copy the model id exactly. resp = client . chat . completions . create ( model = " gpt-5.5 " , messages = [{ " role " : " user " , " content " : " Say hello in one sentence. " }], ) If the model name is wrong, you usually get 404 , model_not_found , or a gateway-specific validation error. 4. Test with the smallest possible request Before debugging your whole app, run one tiny request: resp = client . chat . completions . create ( model = " gpt-5.5 " , messages = [{ " role " : " user " , " content " : " ping " }], max_tokens = 20 , ) print ( resp . choices [ 0 ]. message . content ) If this works, the base URL, key, and model are probably fine. Your bug is likely in the app layer: streaming, tool calling, message format, proxy settings, or retry logi