---
name: anth-common-errors
description: 'Diagnose and fix Anthropic Claude API errors by HTTP status code.

  Use when encountering API errors, debugging failed requests,

  or troubleshooting authentication, rate limiting, or input validation issues.

  Trigger with phrases like "anthropic error", "claude api error",

  "fix anthropic 429", "claude not working", "debug claude api".

  '
allowed-tools: Read, Grep, Bash(curl:*)
version: 1.0.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- ai
- anthropic
compatibility: Designed for Claude Code
---
# 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`

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

**Common causes and fixes:**

| Message Pattern | Cause | Fix |
|----------------|-------|-----|
| `messages: roles must alternate` | Consecutive same-role messages | Merge 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 name | Use exact ID: `claude-sonnet-4-20250514` |
| `messages.0.content: empty` | Empty message content | Ensure content is non-empty string or array |
| `tool_result: tool_use_id not found` | Mismatched tool ID | Copy `id` from the `tool_use` block exactly |

### 401 — `authentication_error`

```bash
# 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](https://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`

```json
{"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](https://status.anthropic.com).

## Quick Diagnostic Script

```bash
# 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

```python
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

- [Error Types Reference](https://docs.anthropic.com/en/api/errors)
- [Rate Limits](https://docs.anthropic.com/en/api/rate-limits)
- [API Status](https://status.anthropic.com)

## Next Steps

For comprehensive debugging, see `anth-debug-bundle`.


---
Source attribution: jeremylongshore
Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/main/plugins/saas-packs/anthropic-pack/skills/anth-common-errors/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: jeremylongshore
Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/main/plugins/saas-packs/anthropic-pack/skills/anth-common-errors/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Customer Support
Roles: Backend Developer, ML / AI Engineer, Technical Support
Specialties: API, Backend, Design, Frontend, Testing
Tools: Anthropic
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 638ba6d21d6f3c70009e39649d8e6e9c96b6bf385bae24f467c4ef010893e5cd