OpenSkillIndex← back to search
claude-code

Claude-code-plugins anth-common-errors

install
source · Clone the upstream repo
git clone https://github.com/jeremylongshore/claude-code-plugins-plus-skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/jeremylongshore/claude-code-plugins-plus-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/saas-packs/anthropic-pack/skills/anth-common-errors" ~/.claude/skills/jeremylongshore-claude-code-plugins-anth-common-errors && rm -rf "$T"
manifest: plugins/saas-packs/anthropic-pack/skills/anth-common-errors/SKILL.md
tags
#saas#ai#anthropic
source content

Anthropic Common Errors

Overview

Quick reference for all Claude API error types with exact HTTP codes, error bodies, and fixes. The API returns errors as JSON: 

{"type": "error", "error": {"type": "...", "message": "..."}}
.

Error Reference

400 — 
invalid_request_error

{"type": "error", "error": {"type": "invalid_request_error", "message": "messages: roles must alternate between \"user\" and \"assistant\""}}

Common causes and fixes:

Message PatternCauseFix
messages: roles must alternate
Consecutive same-role messagesMerge adjacent user/assistant messages
max_tokens: must be >= 1
Missing or zero 
max_tokens
Always set 
max_tokens
(required param)
model: invalid model id
Typo in model nameUse exact ID: 
claude-sonnet-4-20250514
messages.0.content: empty
Empty message contentEnsure content is non-empty string or array
tool_result: tool_use_id not found
Mismatched tool IDCopy 
id
from the 
tool_use
block exactly

401 — 
authentication_error

# Verify your key is set and valid
echo $ANTHROPIC_API_KEY | head -c 15  # Should show: sk-ant-api03-...

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

403 — 
permission_error

API key lacks required permissions. Generate a new key at console.anthropic.com.

404 — 
not_found_error

Invalid endpoint or model. Check you're using 

https://api.anthropic.com/v1/messages
and a valid model ID.

429 — 
rate_limit_error

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

Check headers for details:

  • retry-after
    — seconds to wait
  • anthropic-ratelimit-requests-limit
    — RPM cap
  • anthropic-ratelimit-tokens-limit
    — TPM cap
  • anthropic-ratelimit-tokens-remaining
    — tokens left this window

Fix: The SDK handles 429 with automatic retry (configurable via 

maxRetries
). For manual handling, see 
anth-rate-limits
.

529 — 
overloaded_error

API is temporarily overloaded. Retry after 30-60 seconds. Not counted against rate limits.

500 — 
api_error

Internal server error. Retry with exponential backoff. If persistent, check status.anthropic.com.

Quick Diagnostic Script

# 1. Check API status
curl -s https://status.anthropic.com/api/v2/status.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['status']['description'])"

# 2. Verify key format
echo $ANTHROPIC_API_KEY | grep -qE '^sk-ant-api03-' && echo "Key format OK" || echo "Key format WRONG"

# 3. Test minimal request
curl -s -w "\nHTTP %{http_code}" https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":8,"messages":[{"role":"user","content":"1+1="}]}'

SDK Error Handling

import anthropic

try:
    message = client.messages.create(...)
except anthropic.AuthenticationError as e:
    print(f"Auth failed: {e.status_code}")
except anthropic.RateLimitError as e:
    print(f"Rate limited. Retry after: {e.response.headers.get('retry-after')}s")
except anthropic.BadRequestError as e:
    print(f"Invalid request: {e.message}")
except anthropic.APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")
except anthropic.APIConnectionError:
    print("Network error — check connectivity")

Resources

Next Steps

For comprehensive debugging, see 

anth-debug-bundle
.