Troubleshooting

Common issues and solutions when using 3xCoder.

Connection Issues

1. 401 Unauthorized / Invalid API Key

Cause: Your API key is incorrect, expired, or revoked.

Solution:

• Verify your API key in the dashboard
• Ensure the key starts with sk-
• Check that the key hasn't been revoked
• Create a new key if needed

# Test your key
curl -s -o /dev/null -w "%{http_code}" \
  https://api.3xcoder.com/v1/models \
  -H "Authorization: Bearer sk-your-key"
# Should return 200

2. 403 Forbidden

Cause: Your key doesn't have permission for the requested model or endpoint.

Solution:

• Check model access settings for your key in the dashboard
• Verify your account plan includes the requested model

3. 404 Not Found / Model Not Found

Cause: The model ID is incorrect or the model is not available.

Solution:

• List available models: curl https://api.3xcoder.com/v1/models -H "Authorization: Bearer sk-your-key"
• Check for typos in the model name
• Common model IDs: gpt-4o, claude-sonnet-4-20250514, gemini-2.5-pro

4. 429 Too Many Requests / Rate Limited

Cause: You've exceeded your key's rate limit.

Solution:

• Wait a moment and retry
• Check your rate limit settings in the dashboard
• Request a rate limit increase if needed
• Implement exponential backoff in your application

5. 500 Internal Server Error

Cause: An error occurred on the relay or upstream provider.

Solution:

• Retry the request after a few seconds
• If the issue persists, check if the upstream provider is having issues
• Try a different model to isolate the problem

6. Connection Timeout

Cause: Network issues or the server is unreachable.

Solution:

• Check your internet connection
• Test connectivity: curl -v https://api.3xcoder.com/v1/models
• If behind a proxy, configure HTTPS_PROXY
• Try from a different network

Tool-Specific Issues

7. Claude Code Won't Start

Symptoms: Claude Code shows authentication error or hangs.

Solution:

• Verify ANTHROPIC_BASE_URL is set correctly (no trailing slash)
• Check settings.json path for your OS (see Deploy Claude Code)
• Try launching with env vars directly:

ANTHROPIC_BASE_URL="https://api.3xcoder.com" \
ANTHROPIC_API_KEY="sk-your-key" \
claude

8. CodeX CLI Config Not Working

Symptoms: CodeX ignores your configuration.

Solution:

• Verify config.toml and auth.json are in the correct directory
• Check file permissions
• Try environment variables instead:

OPENAI_BASE_URL="https://api.3xcoder.com/v1" \
OPENAI_API_KEY="sk-your-key" \
codex "test"

9. Gemini CLI Authentication Error

Symptoms: Gemini CLI shows "Invalid credentials".

Solution:

• Check settings.json has the correct base URL: https://api.3xcoder.com/v1beta/models
• Verify the API key has Gemini model access
• Re-run CC-Switch and re-apply the configuration

10. Streaming Not Working

Symptoms: Responses arrive all at once instead of streaming.

Solution:

• Ensure stream: true is set in your request
• Check if your client/library supports SSE streaming
• Some proxies buffer SSE — try connecting directly
• Test with curl:

curl -N https://api.3xcoder.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-key" \
  -d '{"model":"gpt-4o","stream":true,"messages":[{"role":"user","content":"Count from 1 to 5."}]}'

Configuration Issues

11. Wrong Base URL Format

Different tools expect different URL formats:

Tool	Base URL
OpenAI SDK / CodeX	https://api.3xcoder.com/v1
Claude Code	https://api.3xcoder.com
Gemini CLI	https://api.3xcoder.com/v1beta/models
CherryStudio (Anthropic)	https://api.3xcoder.com/v1/messages
CherryStudio (Gemini)	https://api.3xcoder.com/v1beta/models

12. Environment Variables Not Taking Effect

Solution:

• Open a new terminal window after setting variables
• Verify the variable is set: echo $OPENAI_API_KEY (or echo $env:OPENAI_API_KEY on PowerShell)
• For permanent variables, add them to your shell profile:
  • Linux/macOS: ~/.bashrc or ~/.zshrc
  • Windows: $PROFILE (PowerShell profile)

13. SSL/TLS Errors

Symptoms: SSL certificate problem or UNABLE_TO_VERIFY_LEAF_SIGNATURE

Solution:

• Ensure your system clock is correct
• Update your CA certificates
• If behind a corporate proxy, you may need to add the proxy's CA cert
• As a last resort (not recommended for production): export NODE_TLS_REJECT_UNAUTHORIZED=0

Debug Commands

Quick commands to diagnose issues:

# Test API connectivity
curl -v https://api.3xcoder.com/v1/models \
  -H "Authorization: Bearer sk-your-key"

# Test chat completion
curl https://api.3xcoder.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-key" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"ping"}]}'

# Check DNS resolution
nslookup api.3xcoder.com

# Test network latency
curl -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\n" \
  -o /dev/null -s https://api.3xcoder.com/v1/models \
  -H "Authorization: Bearer sk-your-key"