Error Code Reference

Reference for QCode.cc API error codes: 400/401/402/403/429/500/502/503/529 semantics, typical causes and proven fixes, including INSUFFICIENT_BALANCE

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 -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

# 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)

402 - Payment Required¶

The upstream channel refused this request. This is usually not a problem with your key or your configuration — requests from the same key to other models at the same time normally succeed.

What you see¶

Error: 402 Payment Required

In Claude Code it usually looks like the request simply failing with no response content; from a script or SDK you get HTTP 402.

Common causes¶

1. The upstream channel is temporarily unavailable: the QCode gateway never generates a 402 itself — it relays the status returned by the upstream

2. Concentrated on one model: at any given moment one model may see a high 402 rate while the others are completely fine

3. Depends on the endpoint domain: different domains route through different upstream paths, and the chance of hitting a 402 can differ substantially

4. Not related to your balance: running out of account balance or plan quota does not return 402 — that case says "daily cost limit reached", see the FAQ

What to do¶

1. Switch model (most effective)

# Switch inside a session
/model sonnet

# Or specify at launch
claude --model claude-sonnet-5

2. Switch endpoint domain

# Mainland China
export ANTHROPIC_BASE_URL=https://asia.qcode.cc/api

# Global (Route 53 picks the nearest node)
export ANTHROPIC_BASE_URL=https://api.qcode.cc/api

All four domains take the same key, so switching needs no other configuration change. See Endpoints & API Formats.

3. Don't write a tight retry loop

A 402 does not go away by resending immediately; hammering only makes it worse. Use exponential backoff, or just switch model — see "Error handling best practices" on this page.

4. If it persists, contact support

Include the time it happened, the model id and the endpoint domain, and reach us through live chat or hi@qcode.cc.

INSUFFICIENT_BALANCE / Insufficient account balance¶

Some 402/403 responses carry JSON like "code":"INSUFFICIENT_BALANCE", "message":"Insufficient account balance". This does not mean your QCode balance ran out. It is a temporary condition on one upstream channel passed through verbatim — unrelated to your account. When your own quota is used up, the message you actually see is "Daily cost limit reached" (see FAQ).

What to do: wait and retry / switch model / switch access domain (steps ①–③ above all apply); if it persists, contact support with the request id. Full checklist: troubleshooting guide.

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://api.qcode.cc/api

1. Verify API endpoint configuration

2. Confirm plan includes required features

3. Contact support to verify permissions

INSUFFICIENT_BALANCE (when it appears on a 403)¶

If a 403 Forbidden body contains INSUFFICIENT_BALANCE / Insufficient account balance, this is again usually a temporary upstream-channel condition relayed verbatim — not your account being restricted. Handle it as in the same-named subsection of the 402 section; see the troubleshooting guide for the full order.

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

E015 - Conversation Context Overflow¶

Triggered when the conversation context approaches the model's capacity limit (~95%). QCode.cc wraps this error as a 429 response to trigger a retry:

429 {"error":{"code":"E015","message":"Internal server error"},"status":500}

Solution: See the "Long Session Overflow Prevention" section in Context Management.

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 api.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

MCP Server Errors¶

Errors that can come from MCP server configuration or runtime.

Symptoms¶

MCP server "xxx" failed to start
MCP connection timed out
MCP tool execution failed

Common Causes¶

1. Wrong server command: npx package name typo or not installed

2. Missing environment variables: the token the MCP server needs is not set

3. Timeout: server start-up or execution takes too long

4. Insufficient permissions: file system / database access denied

Solutions¶

# Check server status with /mcp
/mcp

# Diagnose configuration issues with /doctor
/doctor

# Manually test whether the MCP server can start
npx -y @modelcontextprotocol/server-filesystem /tmp

1. Check connection status with /mcp

2. Run automatic diagnostics with /doctor

3. Verify the format of ~/.claude/settings.json or .mcp.json

4. Make sure required environment variables are set ($GITHUB_TOKEN etc.)

5. Increase timeouts with the MCP_TIMEOUT and MCP_TOOL_TIMEOUT environment variables

General Troubleshooting Steps¶

When encountering any error, follow these steps:

0. Run automatic diagnostics¶

# Claude Code's built-in diagnostic tool
/doctor

This automatically checks common configuration issues: environment variables, API connectivity, MCP server status and more.

1. Check Network Connection¶

# Test API endpoint connectivity
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

# Test DNS resolution
nslookup api.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)