anth-common-errors

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 <[e-mail]>
tags	["saas","ai","anthropic"]
compatible-with	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

{"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

# Verify your key is set and valid
echo $ANTHROPIC_API_KEY |  -c 15  


curl -s https://api.anthropic.com/v1/messages \
  -H  \
  -H  \
  -H  \
  -d