Troubleshooting

401 Authentication Error

Symptom: Claude Code returns "Authentication error" or "Invalid API key".

Steps to resolve:

1. Confirm your API key format is correct (should start with ck-):

echo $ANTHROPIC_API_KEY
# Should output ck-xxxxxxxxxxxx

2. Verify the key is valid with curl:

curl -s https://api.chuizi.ai/v1/key/info \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" | jq

3. If this returns an error, the cause is likely:
   • Key was deleted or disabled -- check key status at app.chuizi.ai
   • Key was partially copied -- recopy the full key
   • Environment variable not loaded -- run source ~/.zshrc or open a new terminal

Connection Timeout

Symptom: Requests hang for a long time before timing out.

Steps to resolve:

1. Test connectivity to Chuizi.AI:

curl -I https://api.chuizi.ai/health

2. Confirm ANTHROPIC_BASE_URL is set correctly:

echo $ANTHROPIC_BASE_URL
# Should output https://api.chuizi.ai/anthropic

3. Common causes:
   • Network requires a proxy -- set the HTTPS_PROXY environment variable
   • DNS resolution issues -- try using 1.1.1.1 or 8.8.8.8 as your DNS server
   • Firewall blocking -- ensure HTTPS outbound to api.chuizi.ai is allowed

Prompt Caching Not Working

Symptom: Costs are not reduced as expected, no cache_read_input_tokens visible in the dashboard.

Steps to resolve:

1. Confirm you're using the /anthropic endpoint:

echo $ANTHROPIC_BASE_URL
# Must be https://api.chuizi.ai/anthropic
# If set to https://api.chuizi.ai/v1, caching behavior differs

2. Check the request log in the dashboard for these usage fields:

   • cache_creation_input_tokens -- tokens written to cache on first request
   • cache_read_input_tokens -- tokens served from cache on subsequent requests

3. Common reasons caching doesn't activate:

   • System prompt is too short -- Anthropic requires at least 1024 tokens to trigger caching
   • Too much time between requests -- cache expires after approximately 5 minutes
   • Request prefix changes between calls -- caching requires identical prefixes across consecutive requests

Unexpectedly High Costs

Symptom: Actual spending is higher than expected.

Steps to resolve:

1. Log in to app.chuizi.ai and check the Billing page

2. Review individual request logs, paying attention to:

   • Output token count -- Claude Code can sometimes generate large amounts of code
   • Model used -- check if Opus ($75/1M output) was used instead of Sonnet ($15/1M output)
   • Cache hit rate -- if caching isn't working, input token costs will be higher

3. Optimization tips:

   • Use Sonnet for daily tasks, switch to Opus only for complex work
   • Use Haiku for simple tasks to save costs
   • Make sure prompt caching is working (see previous section)

429 Rate Limit

Symptom: "Rate limit exceeded" error returned.

Rate limits should be rare when using Chuizi.AI. If you encounter one:

1. Check if your key has custom rate limits -- review key settings in the dashboard
2. The default limit is 30 RPM per model, which is more than enough for normal Claude Code usage
3. If you genuinely need higher limits, contact support for an adjustment

Empty or Truncated Response

Symptom: Claude Code's response cuts off abruptly or returns empty content.

Possible causes:

1. Hit the max_tokens limit -- model output has a maximum length. Claude Code usually handles this automatically, but extremely long code generation can trigger the limit

2. Network interruption -- network fluctuations during streaming can break the connection

3. How to investigate:

   • Check the request in the dashboard log for status_code and output_tokens
   • If output_tokens is very high and near the limit, the truncation is due to length constraints
   • Try breaking the task into smaller steps

Model Not Available

Symptom: After switching models, you get a "model not found" error.

Steps to resolve:

1. Make sure you're using the full model name:

> /model claude-sonnet-4-6

Do not use abbreviations or deprecated names.

2. List available models:

curl -s https://api.chuizi.ai/anthropic/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" | jq

Getting Help

If none of the above resolves your issue:

1. Gather the following information:

   • Claude Code version (claude --version)
   • Operating system and terminal
   • Complete error message
   • Generation ID from the request log (starts with gen-)

2. Contact options:

   • In-app feedback: app.chuizi.ai > Settings > Feedback
   • GitHub Issues: github.com/chuizi-ai/chuizi-ai

Next Steps

• Configuration Guide — verify your environment variable setup
• Error Codes Reference — complete list of API error codes
• Rate Limits — understand rate limiting behavior