Cherry Studio errors look varied, but they can be divided into layers: whether authentication passed, whether the address and model are correct, whether the request was sent, whether the upstream is rate-limiting, and whether the response was truncated in transit. Troubleshooting by layer is more effective than repeatedly reinstalling the client.

This article categorizes errors by 401, 404, 429, connection failures, streaming interruptions, and knowledge base errors, and gives troubleshooting order, diagnostic commands, and evidence-collection methods. Interface names and log entry points may change between versions; use your current version as the reference.

Note: Cherry Studio is a product of its respective owner, and OpenAI is a trademark of its respective owner. This article is a technical troubleshooting guide only and has no affiliation with the relevant vendors; models and pricing follow the site's model pricing.

1. Fix the troubleshooting order first

When an error occurs, save four things first: the HTTP status code, the error message in the response body, the request time, and the request ID returned by the gateway. Without them you can only describe "it failed once, roughly"; with them you can find the specific request and upstream.

Then follow this order, changing only one variable at a time:

  1. Request the gateway directly with curl to confirm whether the address, key, and model are valid.
  2. If curl works but the client does not, check client configuration, proxy, and protocol type.
  3. If neither curl nor the client works, check the key, quota, model ID, and gateway status.
  4. If only long answers or the knowledge base fail, check streaming, timeouts, and the embedding model.
Symptom Common cause Check first
401 authentication error Wrong, expired, space-containing key, or key from another platform Whether key and Base URL match
404 Not Found /v1 added or missing in the path The end of the API address
model not found Model ID misspelled, wrong case, or not enabled Model ID and pricing page
429 Too Many Requests Concurrency, rate, or quota cap Response headers and gateway usage
Connection timeout Proxy, DNS, firewall, or certificate System proxy and network
Answer stops midway Streaming connection cut by proxy or timeout Turn off streaming to compare

2. 401: key and authentication

401 means the server does not recognize the key. Common causes:

  • Spaces, line breaks, or quotes came along when copying, so the string actually sent is incomplete.
  • The key belongs to another platform but was entered under the current Base URL.
  • The key was deleted or rotated, its project was disabled, or its quota is exhausted.
  • The client failed to save, so the input box looks populated but the request contains nothing.
  • An Anthropic or Gemini protocol is used to request an OpenAI-compatible endpoint, so the authentication header format does not match.

The fix is to paste the key again and confirm there are no leading or trailing spaces, then confirm that the Base URL and key come from the same platform. If the client supports "Check" or "Test Connection," use it first, then retest with curl. If curl works but the client returns 401, focus on whether the client actually saved the key and whether the protocol type is wrong.

3. 404 and model not found

404 does not necessarily mean the endpoint is offline; it is more often a path concatenation error. Common cases:

  • The Base URL contains the full endpoint address, and the client appends /chat/completions again, producing a duplicate path.
  • /v1 is missing where it should be present, or added where it should not be.
  • The provider type is wrong, for example an OpenAI-compatible endpoint configured as Anthropic or Gemini.
  • The model ID's capitalization, date suffix, or hyphens do not match the pricing page.
  • The model exists, but the current key does not have permission to use it.

model not found and 404 should be viewed separately: the former means the address works but the model is wrong; the latter may mean even the route was not matched. First use /v1/models to see which models the gateway returns; if the list endpoint is unavailable, copy the exact ID from the model pricing page, add it manually, and retry.

4. 429: rate limit, concurrency, or quota

429 has at least two meanings, and the handling is completely different:

  • Rate or concurrency exceeded: too many requests in a short period, or multiple sessions or agents open at once.
  • Quota or balance insufficient: the key's project has no available quota, or the budget cap was reached.

Check the response body and headers first. retry-after indicates the suggested wait time; if the error message explicitly mentions quota or balance, do not keep backing off and retrying — confirm the quota in the console first. Only pure rate limiting is suitable for exponential backoff, and it should include random jitter so all clients do not retry in the same second.

Opening multiple assistants and batch-comparing models in Cherry Studio can easily amplify concurrency without your realizing it. During troubleshooting, keep only one session and one model first, and restore gradually after confirming single requests work.

5. Connection failures, SSL, and proxies

Connection failures often appear as a spinning indicator followed by a timeout, inability to connect, or certificate error. Cherry Studio usually has three proxy modes: system proxy, custom proxy, and no proxy; they are under system or general settings, and names depend on the current version.

Troubleshooting order:

  1. Confirm the system proxy or VPN is running and the client is using "system proxy" mode.
  2. If a custom proxy is entered, confirm the address and port are correct, for example http://127.0.0.1:7890.
  3. Check the proxy bypass list to confirm the target domain is not incorrectly excluded or forced through the proxy.
  4. Temporarily switch to "no proxy" for comparison to determine whether the proxy path causes the problem.
  5. When the corporate network performs TLS interception, confirm the system certificate and the client's trust chain are complete.
  6. Check whether the system time is accurate; a large time offset can cause certificate validation failure.

A common mistake is putting the proxy address into the API address. The API address should be the HTTPS address of the model gateway; the proxy goes in proxy settings, and the two should not be mixed.

6. Streaming output interruptions

Streaming responses rely on long connections. A common pattern is that the first token appears, then it stops after seconds or tens of seconds, or only part of the content is displayed. Causes include proxy buffering, idle timeouts, gateway timeouts, and network switching.

During troubleshooting, turn off streaming output first and retry the same question. If non-streaming works, the problem is basically in the transport path; focus on the timeout settings of proxy software, firewalls, and reverse proxies. Reverse proxies should disable response buffering and extend read timeouts; otherwise SSE is buffered and returned all at once, or cut off midway.

Also distinguish "the model actually stopped" from "the connection was cut." The former usually has an end marker; the latter often has no error code, leaving only half the text. Record the two cases separately so you can later judge whether the problem is the client, gateway, or network.

7. Knowledge base and embedding errors

Knowledge base errors usually occur in embedding or retrieval rather than the chat endpoint:

  • Only a chat model is configured, with no working embedding model.
  • The embedding model does not support the current embedding endpoint, or the returned vector dimensions do not match the index.
  • Uploaded files fail to parse, for example a scanned PDF with no extractable text.
  • The embedding model was changed without rebuilding the index, so old vectors and new queries do not match.
  • The reranking or retrieval service is unreachable, appearing as empty retrieval or timeouts.

Cherry Studio's knowledge base can use keyword retrieval or add an embedding model for hybrid retrieval; switching models triggers a rebuild in the interface. Confirm the new model is callable before rebuilding, and do not change chunking parameters at the same time, or you will not know what caused the change in results. Specific entry points follow the current version's documentation.

8. Logs, diagnostic commands, and evidence collection

Cherry Studio provides a developer mode that can be enabled in settings to show the request call chain for locating model and tool errors; the entry point depends on the current version. On the gateway side, retain the request ID, model name, latency, and token usage; matching timestamps on both sides makes it easier to determine which segment has the problem.

Use curl for a minimal reproduction first:

export ZSQH_API_KEY="sk-your-key"

# 1. Check whether the address and key are valid
curl -sS "https://ai.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -w "\nHTTP %{http_code}\n"

# 2. Check whether the model is callable
curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-model-id","messages":[{"role":"user","content":"Reply with OK only"}]}' \
  -w "\nHTTP %{http_code}\n"

# 3. Check the TLS handshake and certificate chain separately
openssl s_client -connect ai.zhongshangqihang.com:443 -servername ai.zhongshangqihang.com </dev/null

The three commands correspond to three questions: key and address, model and parameters, TLS and certificate. Whichever step fails, continue troubleshooting at that layer; do not change the key, address, and model at the same time.

FAQ

Does changing the key always fix a 401?

Not necessarily. Changing the key can rule out a problem with the key itself, but if the Base URL and key platform do not match, the protocol is wrong, or the client did not actually save the key, changing keys will not help. First confirm where the request is actually sent.

Does a 404 mean the model is offline?

In most cases the Base URL path is wrong or the model ID is incorrect. First request /v1/models with curl, then check the model identifier against model pricing; only when both steps are normal should you consider whether the model has been retired.

Does a 429 always mean I should reduce concurrency?

Not necessarily. Read the error message first: only pure rate limiting requires lower concurrency and backoff; when quota is insufficient, slowing down is meaningless, and you should confirm the balance or budget in the console. The retry-after response header helps determine the wait time.

Why do only streaming answers break?

Streaming relies on long connections and is more likely to be cut by proxy buffering, firewall idle timeouts, or reverse proxy timeouts. Turn off streaming for comparison; if non-streaming works, check the proxy and timeouts first rather than repeatedly reinstalling the client.

Should knowledge base errors and chat errors be investigated separately?

Yes. Chat goes through the chat endpoint, while the knowledge base also involves file parsing, embedding models, vector indexes, and retrieval services. First confirm the chat model works, then separately check whether the embedding model is callable, whether dimensions match, and whether the index needs rebuilding.

Next steps

The troubleshooting order can be summarized in one sentence: curl first, then the client; status code first, then logs; change only one variable at a time. If you need a unified OpenAI-compatible entry point, request logs, and usage management, sign up for the ZSQH AI Gateway; models and pricing follow the model pricing page.

Related reading: