curated-clade-common-errors

jeremylongshore/claude-code-plugins-plus-skillsDeveloper ToolsAudit pendingSnapshot e23aed17a652

Summary

This source did not publish a separate summary. Review SKILL.md before using the skill.

SKILL.md

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

Tier	RPM	TPM (input)	TPM (output)
Tier 1 (free)

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

// 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;
}

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

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');
  }
}

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

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

// 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)];
}

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

curated-clade-common-errors

Summary

SKILL.md

Anthropic Common Errors

Overview

Error Reference

Instructions

Step 1: `authentication_error` (401)

Step 2: `rate_limit_error` (429)

Step 3: `overloaded_error` (529)

Step 4: `invalid_request_error` (400)

Step 5: `not_found_error` (404)

Step 6: Content too long (context window)

Quick Diagnostic

Output

Error Handling

Examples

Resources

Next Steps

Prerequisites

Related skills

curated-clade-common-errors

Summary

Anthropic Common Errors

Overview

Error Reference

Instructions

Step 1: authentication_error (401)

Step 2: rate_limit_error (429)

Step 3: overloaded_error (529)

Step 4: invalid_request_error (400)

Step 5: not_found_error (404)

Step 6: Content too long (context window)

Quick Diagnostic

Output

Error Handling

Examples

Resources

Next Steps

Prerequisites

Related skills

Step 1: `authentication_error` (401)

Step 2: `rate_limit_error` (429)

Step 3: `overloaded_error` (529)

Step 4: `invalid_request_error` (400)

Step 5: `not_found_error` (404)