Troubleshooting OpenAI-Compatible APIs: Resolving 401, 404, and Model Name Errors

1. Troubleshooting Order: Validate the Request Path Before Changing the Client

After connecting to a third-party OpenAI-compatible API, errors usually come from one of three areas: the request is sent to the wrong URL, the server rejects the supplied API key, or the model name is not recognized. More than one issue may exist at the same time.

Repeatedly changing settings in the client makes it difficult to identify the actual cause. A more reliable process has two stages:

1. Send a generic HTTP request directly to the API.
2. After the request succeeds, enter the same URL, API key, and model name into the client.

If the client still fails, change only one variable at a time and record the result.

Direct HTTP testing removes interference from the client. A client may cache old settings, load overriding values from system environment variables, or wrap the server’s error message. By bypassing these layers, you can see the server’s actual response.

Use a table like the following to record each test. The “Key length” column should contain only the number of characters, never the key itself.

Test	Variable changed	API endpoint	Key length	Model name	HTTP status	error field in response	Request ID
1	Baseline, no changes	https://api.example.com/v1/chat/completions	64	your-model-id	401	Authentication-related message	Record if returned
2	Key only	Same as above	64	your-model-id	200	None	Record if returned
3	Endpoint only	Same as above, with the extra path removed	64	your-model-id	404	Path-not-found message	Record if returned
4	Model name only	Same as above	64	Actual ID from the model list	200 or 400	Model-related message	Record if returned

Change only one variable per row. The first row is the baseline, and every later row should be compared with it. Preserve the original error body; it is more reliable than memory when reviewing the issue later.

2. First Step: Validate the Request with HTTP

Create a request body file named body.json:

{
  "model": "your-model-id",
  "max_tokens": 64,
  "messages": [{"role": "user", "content": "Hello"}]
}

Replace the model name with the exact ID returned by the model-list endpoint. The process for obtaining it is described in Section 5.

max_tokens sets an upper limit for the response length. It does not mean that every request has a fixed cost. Actual billing rules depend on the provider’s documentation. Using a small value can reduce waiting time and usage during testing.

Do not place the API key directly in a command or script. Read it from the API_KEY environment variable instead:

export API_KEY="your-api-key"

Then send the request. The -o option saves the response body to a file, while -w prints the HTTP status code in the terminal:

curl -sS -o response.json -w "HTTP status: %{http_code}\n" \
  -X POST "https://api.example.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  --data @body.json
cat response.json

A successful request normally returns status 200, and response.json contains a choices field. For a failed request, check the status code first, followed by the error description in the response body.

Avoid adding -v casually during troubleshooting. It prints request headers, including the Authorization header. If you need to save verbose logs, remove or redact that line first.

HTTP Status Code Reference

Status code	Common meaning	What to check first
200	Request succeeded	No action needed; continue to client configuration
400	Invalid request body or parameter	JSON syntax, messages structure, and model name
401	Authentication failed	Whether the key is empty, contains whitespace, or includes the Bearer prefix
403	Access to the resource is not permitted	Whether the account has access to the model and whether the key has sufficient permissions
404	Path or resource not found	The endpoint path and whether the model exists
429	Too many requests or insufficient quota	Rate limits, account balance, or quota
500, 502, 503	Server-side failure	Retry later and check the provider’s status page

A missing model may return 400 in one service and 404 in another. Use the provider’s documentation and the response body to determine the cause instead of relying on the status code alone.

3. 401 Errors: Credentials and Authentication

A 401 response means the server did not accept your identity. It does not necessarily mean that the endpoint URL is wrong. A request that reaches the authentication stage has already passed the relevant routing step.

Common causes include:

1. The environment variable was not set in the current shell. For example, after reopening a terminal, API_KEY may be empty and the request header becomes Bearer.
2. Spaces or line breaks were copied into the key.
3. The Bearer prefix is missing or misspelled.
4. The key belongs to another provider, has been revoked, or has expired.
5. A client or proxy overwrote the Authorization header while forwarding the request.

Check the key length without printing the key itself:

echo ${#API_KEY}

If the result is 0, the variable is empty and must be set again. If its length differs from the length shown in the provider’s console, copy the key again. Do not paste it into a chat window or screenshot.

To fix the issue, generate or copy the key again, verify that it has no leading or trailing whitespace, and confirm that the header format is:

Authorization: Bearer your-api-key

After making the change, repeat the request from Section 2. The status should change from 401 to 200 or to another business-level status.

4. 404 Errors: URLs and Paths

A 404 response means that the server could not find the requested path. It is usually related to the endpoint URL, but it may also occur when the requested model does not exist.

Start by checking the complete URL. API documentation commonly provides a base URL and an endpoint path. These must be combined correctly:

• Base URL: https://api.example.com/v1
• Endpoint path: /chat/completions
• Complete URL: https://api.example.com/v1/chat/completions

Common path-construction mistakes include:

1. Omitting /v1, resulting in https://api.example.com/chat/completions.
2. Adding /v1 twice, resulting in https://api.example.com/v1/v1/chat/completions.
3. Including /chat/completions in the base URL when the client appends it automatically.
4. Using inconsistent trailing slashes. Some services handle /completions/ and /completions differently.
5. Using a web console URL as the API endpoint.

To verify the path, reuse the curl command from Section 2 and change only the URL. Compare the status codes for the possible forms. If only one form returns 200, use that form.

Align the client configuration with the successful request. Many clients expect a base URL and append the endpoint path automatically. Before configuring the client, check its documentation to determine whether it requires a base URL or a complete endpoint URL.

Update the client’s endpoint to match the successful curl request exactly. Save the configuration and restart the client.

5. Model Name Errors: Query the Model List First

Model-related errors may indicate that the model does not exist, is not available to the account, or is an invalid parameter. The model name must exactly match the ID supported by the server, including capitalization, hyphens, and version suffixes.

Use the model-list endpoint to obtain the available IDs. Most compatible APIs provide a /models path and use the same Bearer authentication:

curl -sS -X GET "https://api.example.com/v1/models" \
  -H "Authorization: Bearer $API_KEY"

The model ID is usually found in the id field within the data array. The following shows the general structure; actual field names depend on the provider’s documentation:

{
  "object": "list",
  "data": [
    {"id": "model-a"},
    {"id": "model-b"}
  ]
}

Copy the returned ID exactly into the model field in body.json. Do not type a model name from memory or use a model ID from another provider.

If the model-list endpoint itself returns 401 or 404, return to Sections 3 and 4. Access to the model list depends on both key permissions and the endpoint path.

Replace the model name in body.json with an ID from the list and repeat the request from Section 2. If the status changes from 400 or 404 to 200, the model name was the cause. If the request still fails, inspect the response body. It often distinguishes between an invalid parameter and an authorization problem.

Finally, enter the exact model ID from the list into the client and send another request to confirm that it works.

6. Final Client Configuration Checks

Only move to this step after the direct HTTP request succeeds. If the client still fails, the problem is likely in the client’s own configuration.

1. System environment variables may override the client settings. Check for provider-related variables such as OPENAI_BASE_URL and OPENAI_API_KEY. Priority rules vary by client, so consult the relevant documentation.
2. The configuration file and the graphical interface may contain different values. Use the configuration that is actually active. If necessary, remove the old settings and enter them again.
3. The client may cache an old URL or key. Fully exit and restart it after making changes. Some clients may also require their cache to be cleared.
4. The client may wrap or replace the original error message. When the displayed error is unclear, return to the command from Section 2 and inspect the raw response body.
5. A proxy or gateway may rewrite the request. If an intermediate layer is involved, verify its forwarding rules and, if necessary, compare the result with a direct request to the provider’s endpoint.

7. Logging and Redaction

Troubleshooting often produces logs, screenshots, and chat messages. These can easily expose an API key.

• Before sharing an error message, check whether it contains an Authorization header or the key itself. Some services may echo part of a key in an error response. Replace sensitive content with ***.
• Close any screen that displays the key before taking a screenshot, or obscure the relevant area.
• Keep response.json and log files for local troubleshooting. Do not upload them to a public repository.
• If you suspect that a key has been exposed, revoke it immediately in the provider’s console and generate a new one.

8. Troubleshooting Checklist

Follow these steps in order and change only one item at a time:

1. Run echo ${#API_KEY} in the current terminal. Confirm that the length is not 0 and matches the provider’s displayed length.
2. Confirm that the request header is Authorization: Bearer your-api-key, with exactly one space between Bearer and the key.
3. Confirm that the endpoint matches the provider’s documented base URL plus endpoint path, without duplicating /v1 or /chat/completions.
4. Use GET /models to retrieve the model list. Confirm that the model name in body.json exactly matches one of the returned IDs.
5. Confirm that body.json is valid JSON and contains both model and messages.
6. After curl returns 200, configure the client. Check whether environment variables or cached settings override the new values.
7. Record the status code, important error fields, and request ID for every test. Use the record to identify which variable caused the failure.
8. Remove all key information from logs and screenshots before sharing them.