Troubleshooting

Insufficient Balance

Q1: "Insufficient Balance" or "Quota Exceeded"

Symptoms: API returns 402 Payment Required or 429 Too Many Requests with balance errors.

• Causes:
  1. Upstream balance exhausted: The enterprise provider account (e.g., Aliyun Cloud Bailian, DeepSeek official) is out of credit.
  2. Gateway rate limit: Cherry Studio rate limits may trigger short-term throttling.
• Solutions:
  • Check in Model Management that the provider API Key is valid.
  • Log in to the upstream provider console (e.g., Aliyun Cloud Bailian console) to check account balance.
  • Temporary workaround: In Group Management, switch the group's default model to a provider with balance.

Model Not Found

Q2: "Model Not Found"

Symptoms: API returns 404 Not Found with The model 'xxx' does not exist.

• Causes:
  • The model name (e.g., qwen-plus) is not in the user's group's allowed models.
• Solutions:
  1. Check request body: Verify the model parameter in the user's code.
  2. Check group permissions: Go to Group Management > select the user's group > check Model routing to ensure the model is selected.
  3. Alias mapping: Verify whether model names are remapped (e.g., qwen-max mapped to qwen3-max).

Authentication Failure

Q3: "401 Unauthorized"

Symptoms: API rejects the connection.

• Causes:
  • Key is incorrect (extra spaces).
  • Key is disabled or expired.
• Solutions:
  • In Key Settings, ensure Enabled is on.
  • Check Expiration time.
  • If needed, delete the old key and generate a new sk- key.

No Healthy Upstream

Q4: "No Healthy Upstream"

Symptoms: API returns 502 Bad Gateway or 503 Service Unavailable.

• Causes:
  • All model channels configured for the user's group are offline or timed out.
• Solutions:
  • Go to Model Management and click Check to test connectivity.
  • Verify the server's network can reach the corresponding provider's API (e.g., dashscope.aliyuncs.com).