Error Code Reference

Common Claude Code error codes and solutions

Error Code Reference¶

This document provides detailed information about various error codes you may encounter while using Claude Code and their solutions.

Error Code Quick Reference¶

429 - Too Many Requests¶

One of the most common errors, indicating too many requests in a short period.

Error Message¶

Error: 429 Too Many Requests
Rate limit exceeded. Please slow down your requests.

Common Causes¶

1. Too frequent requests: Sending multiple requests in rapid succession
2. Too many concurrent requests: Running multiple Claude Code instances simultaneously
3. Token limit reached: Consuming too many tokens in a short time
4. Quota exhausted: Daily/monthly quota depleted

Solutions¶

Immediate Actions:

# Wait 30-60 seconds before retrying
sleep 60 && claude "your question"

Long-term Solutions: 1. Reduce request frequency, avoid rapid consecutive sends 2. Use /compact command to compress context 3. Split large tasks into smaller batches 4. Consider upgrading to a higher quota plan

QCode.cc Advantage: Professional load balancing with multi-account pools to distribute request pressure, effectively reducing 429 errors.

502 - Bad Gateway¶

Indicates the gateway or proxy server received an invalid response from upstream.

Error Message¶

Error: 502 Bad Gateway
The server received an invalid response from the upstream server.

Common Causes¶

1. Upstream temporarily unavailable: Anthropic API server issues
2. Network connection interrupted: Connection dropped during request
3. Proxy server issues: Intermediate node failure
4. Request timeout: Response time exceeded gateway limit

Solutions¶

Immediate Actions:

# Check network connection
curl -I https://asia.qcode.cc/api

# Wait and retry
sleep 30 && claude "your question"

Long-term Solutions: 1. Check local network stability 2. Try switching network environments 3. Use VPN or more stable network 4. Contact support if persistent

QCode.cc Advantage: Multi-region deployment, CDN acceleration, automatic failover, ensuring 99.9% availability.

401 - Unauthorized¶

Invalid API Key or missing valid authentication.

Error Message¶

Error: 401 Unauthorized
Invalid API key or authentication token.

Common Causes¶

1. Incorrect API Key: Missing characters or extra spaces when copying
2. Expired API Key: Subscription has expired
3. Disabled API Key: Banned due to policy violation
4. Environment variable not set: ANTHROPIC_AUTH_TOKEN not configured

Solutions¶

Verify API Key:

# Check environment variable
echo $ANTHROPIC_AUTH_TOKEN

# Confirm correct format (starts with cr_)
# Correct example: cr_xxxxxxxxxxxxxxxxxxxx

Steps: 1. Login to QCode.cc Dashboard to check API Key status 2. Confirm subscription is active 3. If banned, contact support (QCode.cc provides immediate replacement service)

403 - Forbidden¶

Request rejected by server, usually due to insufficient permissions.

Error Message¶

Error: 403 Forbidden
You don't have permission to access this resource.

Common Causes¶

1. Wrong API endpoint: Using incorrect API address
2. Insufficient permissions: Current plan doesn't support this feature
3. Regional restrictions: Some features unavailable in certain regions
4. Account status issues: Account restricted

Solutions¶

# Confirm API endpoint is correct
echo $ANTHROPIC_BASE_URL
# Should be: https://asia.qcode.cc/api

1. Verify API endpoint configuration
2. Confirm plan includes required features
3. Contact support to verify permissions

400 - Bad Request¶

Incorrect request format or invalid parameters.

Error Message¶

Error: 400 Bad Request
The request was malformed or contained invalid parameters.

Common Causes¶

1. Malformed request: Incorrect JSON format
2. Missing parameters: Required parameters not provided
3. Invalid values: Parameter values out of allowed range
4. Encoding issues: Special characters not properly encoded

Solutions¶

# Check for special characters in input
# Ensure request content is properly formatted
claude -p "simple test"

1. Simplify input, exclude special characters
2. Ensure file paths use correct encoding
3. Check command parameter format

500 - Internal Server Error¶

Server encountered unexpected condition preventing request completion.

Error Message¶

Error: 500 Internal Server Error
An unexpected error occurred on the server.

Common Causes¶

1. Server-side bug: API server code issue
2. Resource exhaustion: Server resources temporarily depleted
3. Configuration error: Server misconfiguration

Solutions¶

# Wait and retry
sleep 60 && claude "your question"

# Use verbose mode for more info
claude --verbose

1. Wait a few minutes and retry
2. Check QCode.cc service status
3. Contact support with error details if persistent

503 - Service Unavailable¶

Server temporarily unable to handle requests, usually due to overload or maintenance.

Error Message¶

Error: 503 Service Unavailable
The service is temporarily unavailable. Please try again later.

Common Causes¶

1. Server overload: Request volume exceeds capacity
2. Scheduled maintenance: Server under maintenance
3. Resource exhaustion: Server resources temporarily insufficient

Solutions¶

# Use exponential backoff retry
for i in 1 2 4 8 16; do
  claude "your question" && break
  echo "Retrying, waiting ${i} seconds..."
  sleep $i
done

1. Wait a few minutes and retry
2. Use exponential backoff retry strategy
3. Check service status announcements

529 - Overloaded¶

Claude API-specific error code indicating API service overload.

Error Message¶

Error: 529 Overloaded
The API is temporarily overloaded. Please try again later.

Common Causes¶

1. Global usage surge: Claude service global user spike
2. Peak hours: Concentrated requests during work hours
3. Popular events: Certain events causing usage surge

Solutions¶

# Retry later
sleep 120 && claude "your question"

1. Wait 2-5 minutes and retry
2. Avoid peak hours (US business hours)
3. Use /compact to reduce token usage

QCode.cc Advantage: Multi-account pool rotation mechanism effectively distributes overload pressure.

Connection Timeout¶

Request failed to complete within the specified time.

Error Message¶

Error: Connection timed out
The request timed out while waiting for a response.

Common Causes¶

1. Unstable network: Poor network connection quality
2. Request too large: Too many context tokens
3. Task too complex: AI processing time too long
4. Slow server response: High server load

Solutions¶

# Test network connection
ping asia.qcode.cc

# Use compact mode to reduce context
/compact

1. Check network connection stability
2. Use /compact to compress context
3. Split complex tasks into simpler ones
4. Try more stable network environment

General Troubleshooting Steps¶

When encountering any error, follow these steps:

1. Check Network Connection¶

# Test API endpoint connectivity
curl -I https://asia.qcode.cc/api

# Test DNS resolution
nslookup asia.qcode.cc

2. Verify Environment Variables¶

# Check all relevant environment variables
echo "BASE_URL: $ANTHROPIC_BASE_URL"
echo "AUTH_TOKEN: ${ANTHROPIC_AUTH_TOKEN:0:10}..."

3. Enable Detailed Logging¶

# Use verbose mode for detailed info
claude --verbose

# Or set debug mode
DEBUG=true claude

4. Test Simple Request¶

# Send simple test request
claude -p "say hello"

5. Check Service Status¶

Visit QCode.cc for service status announcements.

Error Handling Best Practices¶

Implement Retry Mechanism¶

# Simple retry script
retry_claude() {
  local max_attempts=3
  local attempt=1

  while [ $attempt -le $max_attempts ]; do
    claude "$@" && return 0
    echo "Attempt $attempt failed, retrying..."
    sleep $((attempt * 2))
    ((attempt++))
  done

  echo "All attempts failed"
  return 1
}

Monitor Usage¶

Regularly check API usage to avoid exceeding quota: 1. Login to QCode.cc Dashboard 2. View usage statistics 3. Set usage alerts

Optimize Requests¶

1. Reduce context: Regularly use /compact or /clear
2. Batch processing: Split large tasks into smaller ones
3. Avoid duplication: Cache common results

Getting Help¶

If the above solutions don't resolve your issue, contact QCode.cc support:

• Live Chat: Bottom right corner of website
• Response Time: 1-2 hours during business hours
• Support Hours: 7×14 (9:00 AM - 11:00 PM daily)

When contacting support, please provide: 1. Complete error message 2. Command executed 3. Time of occurrence 4. API Key prefix (never share full key)