Diagnose and fix Anthropic API errors — authentication, rate limits,
Use when working with common-errors patterns.
overloaded, context length, and content policy issues.
Trigger with "anthropic error", "claude 429", "claude overloaded",
"anthropic not working", "debug claude api".
Diagnose and fix Anthropic API errors — authentication, rate limits,
Use when working with common-errors patterns.
overloaded, context length, and content policy issues.
Trigger with "anthropic error", "claude 429", "claude overloaded",
"anthropic not working", "debug claude api".
Cause: Anthropic API is temporarily at capacity. This is NOT a rate limit — it's server load.
Fix:
// SDK retries 529s automatically. Increase retries if needed:const client = newAnthropic({ maxRetries: 5 });
// For critical paths, implement fallback:try {
returnawait client.messages.create({ model: 'claude-sonnet-4-20250514', ... });
} catch (err) {
if (err instanceofAnthropic.APIError && err.status === 529) {
// Fall back to a different model or providerreturnawait client.messages.create({ model: 'claude-haiku-4-5-20251001', ... });
}
throw err;
}
Step 4: invalid_request_error (400)
{"type":"error","error":{"type":"invalid_request_error","message":"messages: roles must alternate between \"user\" and \"assistant\", but found multiple \"user\" roles in a row"}}
Common causes:
Messages don't alternate user/assistant
max_tokens missing or exceeds model limit
Image too large (>5MB) or wrong format
Invalid model ID
Fix: Validate messages before sending:
functionvalidateMessages(messages: Anthropic.MessageParam[]) {
for (let i = 1; i < messages.length; i++) {
if (messages[i].role === messages[i - 1].role) {
thrownewError(`Messages must alternate roles. Index ${i} has same role as ${i-1}`);
}
}
if (messages[0]?.role !== 'user') {
thrownewError('First message must be from user');
}
}
Cause: Invalid model ID or model not available on your plan.
Fix: Use exact model IDs:
claude-opus-4-20250514
claude-sonnet-4-20250514
claude-haiku-4-5-20251001
Step 6: Content too long (context window)
{"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 204521 tokens > 200000 maximum"}}
Fix:
// 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)];
}
Quick Diagnostic
# 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)
Output
Identified error type and HTTP status code
Root cause determined from error message
Applied fix (key rotation, backoff, input validation, model ID correction)
Verified resolution with successful API call
Error Handling
Error
Cause
Solution
API Error
Check error type and status code
See clade-common-errors
Examples
Each error section above includes the exact JSON error response, cause analysis, and fix code. See Quick Diagnostic section for curl commands to test connectivity.
