anth-common-errors

# 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"...