Error Troubleshooting Guide: Quick Reference for 401 / 429 / 500

Error Troubleshooting Guide

TL;DR: Read the status code first — 401 = bad API key, 403 = no balance / suspended, 429 = rate-limited (exponential backoff), 5xx = Anthropic upstream blip (retry), 400 = your request params are wrong (you fix it).

When you hit an error calling the Claude API, look at the status code first — most issues don't need support and you can fix them yourself. This article groups errors by status code, with the cause, the fix, and when to contact support.

401 Unauthorized: authentication failed

Typical response:

{
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

Possible causes:

1. API key typo (a missing character, an extra space, a substituted character)
2. The API key has been disabled or deleted
3. Wrong header format — not using x-api-key or Authorization: Bearer
4. Using an Anthropic-issued key (you should be using the CodeGateway-issued key, which starts with sk-cg-)

How to fix:

1. Log in to the Dashboard → API Keys page and confirm the key starts with sk-cg-
2. Check that the key status is "Enabled"
3. When copying the key, don't include trailing spaces — using the Dashboard "Copy" button is the safest way
4. Set the key in your .env or environment variables:

export ANTHROPIC_AUTH_TOKEN="sk-cg-YOUR_KEY"
export ANTHROPIC_BASE_URL="https://api.codegateway.dev"

When to contact support: you've worked through every self-service step above and still get 401, even though the Dashboard shows the key is enabled.

403 Forbidden: account disabled / insufficient balance

Typical response:

{
  "error": {
    "type": "permission_denied",
    "message": "insufficient balance"
  }
}

Possible causes:

1. Insufficient balance (most common): the account balance has been spent down
2. The account is temporarily disabled by risk control (very rare)
3. The model isn't covered by your plan (no such restriction today, kept for future use)

How to fix:

1. Dashboard → Overview shows the live balance
2. If your balance is near zero or zero → top up from the Billing page
3. If your balance is healthy but you still get 403 → contact support

When to contact support: balance is ≥ $1 but you still get 403.

429 Too Many Requests: rate limit hit

Typical response:

{
  "error": {
    "type": "rate_limit_error",
    "message": "rate limit exceeded for your plan"
  }
}

Possible causes:

CodeGateway currently rate-limits all users at a single 60 RPM ceiling. A 429 typically means a burst of requests in a short window.

Current rate-limit policy: all users share a single 60 RPM ceiling (60 requests per minute). The TPM (Tokens Per Minute) field is reserved in config but not currently enforced.

CodeGateway has not yet shipped paid plan tiers (Starter / Pro / Team, etc). When we do, we'll announce it and update this doc.

How to fix:

1. Exponential backoff retry: wait 1s after the first failure, 2s after the second, 4s after the third — up to 3 attempts. This is Anthropic's officially recommended strategy.
2. Batching: for offline workloads (bulk log analysis, bulk test-case generation, etc.), insert await sleep(N) to throttle and spread RPM evenly
3. Upgrade your plan: if your peak usage stays close to the limit long-term, upgrade to a higher-RPM plan from the Dashboard

Code example (Node.js exponential backoff):

async function withRetry<T>(fn: () => Promise<T>, maxAttempts = 3): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn()
    } catch (e: any) {
      if (e.status !== 429 || attempt === maxAttempts) throw e
      const delay = 1000 * 2 ** (attempt - 1) // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, delay))
    }
  }
  throw new Error('unreachable')
}

When to contact support: your peak workload exceeds even the Team plan's RPM/TPM — we can configure a custom limit for enterprise users.

500 / 502 / 503: upstream errors

Typical response:

{
  "error": {
    "type": "api_error",
    "message": "upstream error"
  }
}

Possible causes:

1. 502/503: Anthropic upstream is briefly unavailable (most common, usually recovers within a few minutes)
2. 500: the CodeGateway gateway itself is having a problem (very rare — monitoring alerts immediately)

How to fix:

1. Just retry: 5xx is transient — a dumb exponential backoff retry usually succeeds
2. Don't change the request: 5xx isn't a problem with your request, retrying the exact same request is what you want
3. Still 5xx after 5 minutes → check Anthropic Status
4. Anthropic Status looks healthy but CodeGateway still 5xx → contact support (very rare)

When to contact support: 10+ minutes of continuous 5xx, with Anthropic Status reporting all clear.

400 Bad Request: invalid request parameters

Typical response:

{
  "error": {
    "type": "invalid_request_error",
    "message": "messages: missing required field"
  }
}

Possible causes:

1. Missing required fields (such as model, messages, max_tokens)
2. Field with the wrong type (e.g. messages isn't an array)
3. Misspelled model name (e.g. writing claude-sonnet-4 instead of claude-sonnet-4-6)
4. max_tokens exceeds the model's ceiling
5. Wrong message role order (must alternate user → assistant — you can't have two consecutive user messages)

How to fix:

1. Read the message field carefully — Anthropic's error messages are specific and usually point to the exact problem field
2. Cross-check the request format against the Anthropic official docs
3. Use curl to send a minimal request standalone and confirm the basic parameters

Minimal working request example:

curl https://api.codegateway.dev/v1/messages \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hi"}]
  }'

When to contact support: usually never — 400 means the parameters are wrong, you fix them yourself.

context window exceeded: prompt is too long

Typical response:

prompt is too long: <X> tokens > <max> tokens

Possible causes:

Input + expected output token count exceeds the model's context window (Sonnet 4.6 = 200K tokens, Opus = 200K, Haiku = 200K).

How to fix:

1. Use the Anthropic tokenizer to estimate token count locally
2. Truncate history: keep only the last N turns of the conversation
3. Replace with a summary: summarize long documents with Haiku first, then pass the summary to Sonnet/Opus
4. Chunk it: split a long document into chunks, process each independently, then merge the results

Network errors: connection reset / timeout

If the error doesn't carry an HTTP status code (such as ECONNRESET or ETIMEDOUT), it's at the network layer:

1. Check your local network (can you ping api.codegateway.dev?)
2. Check your proxy settings (especially on a corporate network)
3. SSE streaming requests need a long-lived connection — make sure no intermediate proxy enforces a 60s timeout

Still stuck?

Open the Dashboard → bottom-right feedback widget, and include:

• The error code + the raw error response (json)
• An example request (with the API key removed)
• When it happened (down to the minute)

We'll get back to you with a diagnosis within 24 hours.

FAQ

Q: 401 but the API key looks right — what do I check first?

A: In this order — 1) check the dashboard, confirm the key is enabled; 2) verify there’s no extra whitespace or missing character (use the “copy” button, don’t retype); 3) confirm the header is x-api-key or Authorization: Bearer (not ANTHROPIC_AUTH_TOKEN); 4) if every self-service step passes and you still get 401, contact support.

Q: Persistent 5xx — is it CodeGateway’s problem or Anthropic’s?

A: Check Anthropic Status first (status.anthropic.com). If Anthropic is reporting an incident, wait it out (CodeGateway transparently passes upstream errors through). If Anthropic is fully green and you've been getting 5xx for 10+ minutes, that's CodeGateway-side — ping support immediately.

Q: My streaming (SSE) requests sometimes drop mid-flight. What's going on?

A: Almost always a corporate proxy / firewall killing long-lived connections. Allow-list *.codegateway.dev and disable the intermediate proxy's connection timeout. CodeGateway sends a 15-second keep-alive heartbeat at the Cloudflare edge; if some middlebox strips that heartbeat, the long stream eventually drops.

Related docs

• API Usage Tutorial — basic call examples
• Tiered Markups Explained — billing mechanics
• API Key Security Best Practices — key management

References

• Anthropic API errors
• Anthropic Status
• Anthropic rate limits