After connecting Chatbox to a custom API, most errors do not mean "the model is broken." They fall into four categories: wrong identity, wrong address or model, quota or concurrency limits, and network or TLS failures. Classifying the problem before verifying is far more effective than reinstalling the client repeatedly.

This article works through 401, 404 (including model not found), 429, and connection failures, then covers streaming interruptions, multi-device configuration sync, and log evidence. Interface names follow your current Chatbox version; models and pricing follow the site's model pricing page.

Note: Chatbox is a product and trademark of its respective owner. This article is a technical troubleshooting guide only and does not imply any affiliation. Field names and defaults may differ between versions.

1. Save the evidence before classifying

Symptom Common status code or error First judgment Check first
401 error invalid_api_key, empty response Key or request header Whether the key is complete and belongs to this address
404 / model not found not_found_error Path or model ID Host, API path, model ID
429 Too Many Requests rate_limit_error, insufficient_quota Rate limit or balance Usage, concurrency, billing
Failed to fetch / Network Error No status code Network unreachable DNS, proxy, firewall, TLS
5xx server_error Upstream or gateway failure Retry and record the request ID

Before troubleshooting, record the time, Chatbox version, HTTP status code, response body, and request ID. Without them you can only guess; with them you can tell whether the problem is in the client, the network, or the server.

2. 401: the key was not recognized

A 401 means the server does not recognize the key. Frequent causes include:

  • Spaces, line breaks, or full-width characters were copied along with the key, so it looks identical after pasting but is not;
  • A Chatbox AI license key was entered as an API key in a custom provider;
  • The key was deleted or rotated, or its project was disabled;
  • A key from provider A is being used against provider B's address;
  • The request passes through a corporate proxy, and the proxy returns a 401 login page with HTML instead of JSON.

First confirm the API mode is OpenAI-compatible, then paste the key again. Do not rely on "it looks the same"; bypass the client and test directly:

export ZSQH_API_KEY="sk-your-key"

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"

A 200 with choices means the key and address are valid. If 401 persists, the problem is in how the key was copied, its permissions, or the proxy. A 403 usually means "we recognize you, but you may not use this model"; do not confuse it with 401 and keep swapping keys.

3. 404 and model not found: check the address and the model separately

There are two kinds of 404: a path that does not exist and a model that does not exist. The first is a URL issue; the second is a model ID issue. Chatbox asks for the API host and API path separately, and the most common mistake is a duplicated /v1: the host already ends in /v1 while the path also includes /v1/chat/completions, producing /v1/v1/chat/completions.

There is only one criterion: /v1 should appear exactly once in the final request URL. If the host is https://ai.zhongshangqihang.com, the path can be left empty or filled according to your version's documentation; if the host ends in /v1, do not repeat it in the path. Save the change and retest with "Check" or curl.

model_not_found is unrelated to the path. Model IDs are case-sensitive and include version suffixes and vendor prefixes; copy them from the model pricing page or the console. When adding a model manually, also confirm its type is chat and that capability checkboxes match reality, or the model may not appear, or may fail on the first call.

A failed "Fetch model list" does not necessarily indicate a configuration error. Some gateways do not expose a model-list endpoint, and manually entering the correct model ID still works for conversations.

4. 429: rate limits, concurrency, and balance

A 429 has two meanings: requests are too fast, or there is no quota. OpenAI-compatible APIs commonly use rate_limit_error for the former and insufficient_quota for the latter. Both can be 429, but the treatment is opposite.

  • Requests too fast: reduce concurrency and close extra sessions and clients; long context amplifies token consumption.
  • No quota: check gateway usage and billing, top up or change the key; retrying alone will not recover.
  • If the response header includes Retry-After, wait as instructed; otherwise use exponential backoff with random jitter.
  • Do not click "Check" or resend repeatedly in Chatbox; requests pile up quickly in a short window.
  • One key shared across devices and windows also shares its concurrency quota.

If 429 appears only in long conversations, compress the context or start a new session first, then confirm the model's context window. The "maximum context messages" setting can be lowered, but it only relieves context pressure; it does not replace usage and concurrency management.

5. Connection failures: DNS, proxy, SSL, and firewall

Failed to fetch, Network Error, and endless spinning all mean the request received no valid response. First confirm a browser can open a web page, then test the same domain with curl. If curl also fails, the problem is the network or the gateway; if curl succeeds but Chatbox fails, the problem is usually the client proxy, path joining, or certificate trust.

  • Corporate network: a firewall or security gateway may block unfamiliar domains; ask IT to allow it.
  • Proxy: system proxy, VPN, and the in-app proxy switch may stack; keep only one layer, and do not enter the proxy address as the API host.
  • TLS: self signed certificate, UNABLE_TO_VERIFY_LEAF_SIGNATURE, and expired certificates are common with enterprise TLS inspection; install the corporate root certificate rather than disabling verification.
  • System time: a large clock skew can cause certificate validation failures.
  • Mobile network: different results on Wi-Fi and cellular indicate a local network or DNS issue.

If the error appears on only one machine, compare system proxy, hosts, DNS, and certificates before suspecting the model.

6. Streaming interruptions and "the answer stops halfway"

Chatbox uses streaming output by default. Midway stops usually come from three causes: a proxy or gateway buffering SSE, an idle connection timeout, or the upstream disconnecting during generation. The symptom is a normal first half, an abrupt end, or being stuck on "typing."

Turn streaming off first, if your version offers the switch, and compare with the same question. If non-streaming returns completely, the problem is in the SSE path; then check the proxy's buffering settings, timeout values, and network stability. Long answers, reasoning models, and peak hours trigger this more often; shorten the output or retry at another time.

Also note that reasoning models may "think" for a long time before producing text, which can look like a hang. Wait first, then confirm with a non-streaming request whether there is truly no response.

7. Multiple devices, sessions, and configuration sync

Chatbox stores sessions and settings locally by default. Not seeing history after changing computers or phones is usually not an API failure but data that did not come along. To migrate, use the client's export, import, or backup features; capabilities differ between versions, so follow the current one.

Newer Chatbox versions can import model provider configuration in JSON, bringing the host, model list, and capabilities to another device in one step. Keys should still be managed separately: issue keys per device or per person so a leak requires revoking only one.

If two devices behave differently, compare versions, system proxy, and model configuration before comparing keys. Do not conclude that the current device has a network problem just because "the other one works."

8. Logs and evidence: describe the problem clearly

Log and diagnostic entry points differ between Chatbox versions; some offer export in settings, while others require system logs. Whether or not built-in logs exist, record the following manually:

  • The time of occurrence (with time zone) and whether it reproduces consistently;
  • Chatbox version, operating system, and network environment;
  • The HTTP status code and full response body (with the key removed);
  • The request ID from the response headers;
  • The curl result for the same request, and a streaming versus non-streaming comparison.

When filing an issue, mask the key but keep the model ID, timestamp, and status code. "It cannot connect" alone is usually impossible to diagnose; with this evidence, most problems can be routed in one round.

9. A fixed troubleshooting order

  1. Use curl to reach the gateway directly and confirm whether the key, host, and model are valid.
  2. If curl fails: check DNS, proxy, TLS, firewall, and gateway status.
  3. If curl succeeds but Chatbox fails: check the API type, duplicated /v1, model ID, and client proxy.
  4. For 401 check the key, for 404 check the path and model, for 429 check usage and concurrency, and for connection failures check the network and certificates.
  5. Change one variable at a time, and retest and record the result immediately.

The value of this order is that it separates client problems from server problems. Most so-called Chatbox errors ultimately trace back to one configuration item or one network layer.

For unified management of keys, usage, and model entry points, sign up for the ZSQH AI Gateway; available models and billing follow the model pricing page. Prices may change, so the page at checkout is authoritative.

FAQ

Chatbox shows "Failed to fetch." Is the key wrong?

Not necessarily. The message only means the client received no response; a wrong key is just one possible cause. Test the same host with curl first; if curl also fails, check the network, proxy, and certificates.

Why does curl work while Chatbox cannot connect?

Common causes are the client proxy, a duplicated /v1, the wrong API type, an untrusted system certificate, or a client version that joins paths differently. Compare the final request URL item by item.

Will retrying a 429 eventually recover?

If it is a rate limit, backoff and lower concurrency may recover; if it is insufficient quota, retrying will not help, and you need to check billing or change the key. Read the error type in the response body first.

If fetching the model list fails, can I still add models manually?

Yes. Some gateways do not expose a model-list endpoint, and a manually entered model ID still works, provided the model ID, API type, and host are all correct.

Do sessions and settings sync automatically after changing devices?

Sessions are stored locally by default and may not sync automatically. Migrate with export and import; newer versions can import provider JSON, but keys should still be re-entered and managed separately.

Related reading: