Clade Common Errors

Anthropic Common Errors

Overview

Every Anthropic API error includes a type field and HTTP status code. Here are the real errors you'll hit and how to fix them.

Error Reference

Instructions

Step 1: authentication_error (401)

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

Cause: API key is missing, malformed, or revoked. Fix:

# Verify key exists and starts with sk-ant-
echo $ANTHROPIC_API_KEY | head -c 10
# Should print: sk-ant-api

# Test directly
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "claude-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

Step 2: rate_limit_error (429)

{"type":"error","error":{"type":"rate_limit_error","message":"Number of request tokens has exceeded your per-minute rate limit"}}

Cause: Exceeded requests per minute (RPM) or tokens per minute (TPM). Fix:

// The SDK has built-in retries with backoff
const client = new Anthropic({
  maxRetries: 3, // default is 2
});

// Or handle manually using the retry-after header
try {
  const msg = await client.messages.create({ ... });
} catch (err) {
  if (err instanceof Anthropic.RateLimitError) {
    const retryAfter = err.headers?.['retry-after'];
    await sleep(Number(retryAfter) * 1000 || 5000);
    // retry...
  }
}

Rate limit tiers (as of 2025):

Step 3: overloaded_error (529)

{"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}

Cause: Anthropic API is temporarily at capacity. This is NOT a rate limit — it's server load. Fix:

// SDK retries 529s automatically. Increase retries if needed:
const client = new Anthropic({ maxRetries: 5 });

// For critical paths, implement fallback:
try {
  return await client.messages.create({ model: 'claude-sonnet-4-20250514', ... });
} catch (err) {
  if (err instanceof Anthropic.APIError && err.status === 529) {
    // Fall back to a different model or provider
    return await client.messages.create({ model: 'claude-haiku-4-5-20251001', ... });
  }
  throw err;
}

Step 4: invalid_request_error (400)

{"type":"error","error":{"type":"invalid_request_error","message":"messages: roles must alternate between \"user\" and \"assistant\", but found multiple \"user\" roles in a row"}}

Common causes:

• Messages don't alternate user/assistant
• max_tokens missing or exceeds model limit
• Image too large (>5MB) or wrong format
• Invalid model ID

Fix: Validate messages before sending:

function validateMessages(messages: Anthropic.MessageParam[]) {
  for (let i = 1; i < messages.length; i++) {
    if (messages[i].role === messages[i - 1].role) {
      throw new Error(`Messages must alternate roles. Index ${i} has same role as ${i-1}`);
    }
  }
  if (messages[0]?.role !== 'user') {
    throw new Error('First message must be from user');
  }
}

Step 5: not_found_error (404)

{"type":"error","error":{"type":"not_found_error","message":"model: model_not_found"}}

Cause: Invalid model ID or model not available on your plan. Fix: Use exact model IDs:

• claude-opus-4-20250514
• claude-sonnet-4-20250514
• claude-haiku-4-5-20251001

Step 6: Content too long (context window)

{"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 204521 tokens > 200000 maximum"}}

Fix:

// Count tokens before sending (use Anthropic's token counting)
const count = await client.messages.countTokens({
  model: 'claude-sonnet-4-20250514',
  messages,
});
console.log(`Input tokens: ${count.input_tokens}`);

if (count.input_tokens > 180000) {
  // Truncate conversation history, keeping system + last N messages
  messages = [messages[0], ...messages.slice(-10)];
}

Quick Diagnostic

# Check API status
curl -s https://status.anthropic.com/api/v2/status.json | jq '.status.description'

# Verify API key works
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "claude-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"ping"}]}' | jq '.content[0].text'

# Check current usage/limits
# (No API for this — check console.anthropic.com/settings/limits)

Output

• Identified error type and HTTP status code
• Root cause determined from error message
• Applied fix (key rotation, backoff, input validation, model ID correction)
• Verified resolution with successful API call

Error Handling

Examples

Each error section above includes the exact JSON error response, cause analysis, and fix code. See Quick Diagnostic section for curl commands to test connectivity.

Resources

• Error Types Reference
• Rate Limits
• Anthropic Status

Next Steps

For deeper debugging, see clade-debug-bundle.

Prerequisites

• Anthropic SDK installed (@claude-ai/sdk or anthropic)
• API credentials configured
• Access to application logs or console output

Source: jeremylongshore/claude-code-plugins-plus-skills → skills/.curated/clade-common-errors/SKILL.md

Also appears in: jeremylongshore/claude-code-plugins-plus-skills/plugins/saas-packs/claude-pack/skills/clade-common-errors/SKILL.md