Loading…
What do you do when a Claude API call returns 401 Unauthorized, 429 Too Many Requests, or 500 Internal Server Error? This article groups errors by status code, and walks through the cause, the fix, and whether you need to contact support.
TL;DR
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.
Typical response:
{
"error": {
"type": "authentication_error",
"message": "invalid x-api-key"
}
}Possible causes:
x-api-key or Authorization: Bearersk-cg-)How to fix:
sk-cg-.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.
Typical response:
{
"error": {
"type": "permission_denied",
"message": "insufficient balance"
}
}Possible causes:
How to fix:
When to contact support: balance is ≥ $1 but you still get 403.
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:
await sleep(N) to throttle and spread RPM evenlyCode 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.
Typical response:
{
"error": {
"type": "api_error",
"message": "upstream error"
}
}Possible causes:
How to fix:
When to contact support: 10+ minutes of continuous 5xx, with Anthropic Status reporting all clear.
Typical response:
{
"error": {
"type": "invalid_request_error",
"message": "messages: missing required field"
}
}Possible causes:
model, messages, max_tokens)messages isn't an array)claude-sonnet-4 instead of claude-sonnet-4-6)max_tokens exceeds the model's ceilingHow to fix:
message field carefully — Anthropic's error messages are specific and usually point to the exact problem fieldcurl to send a minimal request standalone and confirm the basic parametersMinimal 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.
Typical response:
prompt is too long: <X> tokens > <max> tokensPossible causes:
Input + expected output token count exceeds the model's context window (Sonnet 4.6 = 200K tokens, Opus = 200K, Haiku = 200K).
How to fix:
If the error doesn't carry an HTTP status code (such as ECONNRESET or ETIMEDOUT), it's at the network layer:
Open the Dashboard → bottom-right feedback widget, and include:
We'll get back to you with a diagnosis within 24 hours.
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.