Anthropic Known Pitfalls Skill

Anthropic Known Pitfalls

Overview

Ten common mistakes when building with the Anthropic API and how to avoid them: forgetting max_tokens (required), system prompt in messages array (wrong), non-alternating messages, unchecked stop_reason, creating client per request, no 529 handling, hardcoded model IDs, expensive output tokens, no streaming, and unnecessary PII.

1. Forgetting `max_tokens`

Unlike OpenAI, max_tokens is required. Omitting it returns a 400 error.

// BAD
await client.messages.create({ model: 'claude-sonnet-4-20250514', messages });

// GOOD
await client.messages.create({ model: 'claude-sonnet-4-20250514', max_tokens: 1024, messages });

2. System Prompt in Messages Array

Claude uses a top-level system parameter, not a system message in the array.

// BAD — this sends "system" as a user message role, which will error
messages: [{ role: 'system', content: '...' }, { role: 'user', content: '...' }]

// GOOD
system: 'You are helpful.',
messages: [{ role: 'user', content: '...' }]

3. Non-Alternating Messages

Messages must strictly alternate between user and assistant.

// BAD — two user messages in a row
messages: [
  { role: 'user', content: 'Hello' },
  { role: 'user', content: 'How are you?' }, // ERROR
]

// GOOD — combine into one or add assistant between
messages: [
  { role: 'user', content: 'Hello. How are you?' },
]

4. Not Checking `stop_reason`

If stop_reason === 'max_tokens', the response was truncated.

if (message.stop_reason === 'max_tokens') {
  // Response is incomplete — increase max_tokens or handle truncation
}

5. Creating Client Per Request

Each new Anthropic() creates a new connection pool. In serverless, this adds latency.

// BAD — new client every request
app.post('/chat', async (req, res) => {
  const client = new Anthropic(); // Cold connection every time
});

// GOOD — reuse across requests
const client = new Anthropic();
app.post('/chat', async (req, res) => {
  await client.messages.create({ ... });
});

6. No Error Handling for 529

529 (overloaded) is common during peak hours. The SDK retries automatically, but you should handle it for critical paths.

7. Hardcoding Model IDs

Model IDs change with new versions. Use environment variables.

const MODEL = process.env.CLAUDE_MODEL || 'claude-sonnet-4-20250514';

8. Ignoring Token Costs

Output tokens cost 5x more than input tokens. A 4096 max_tokens response on Opus costs ~$0.30. Use the smallest max_tokens that works.

9. No Streaming for User-Facing Apps

Without streaming, users stare at a blank screen for 5-30 seconds. Always stream for interactive use.

10. Sending PII Unnecessarily

Don't include user PII in prompts unless the task requires it. Redact before sending.

Quick Reference

| Pitfall | Fix | |---------|-----| | Missing max_tokens | Always include it | | System in messages | Use top-level system param | | Non-alternating messages | Combine or interleave | | Unchecked stop_reason | Check for max_tokens truncation | | Client per request | Module-level singleton | | No 529 handling | SDK retries + fallback model | | Hardcoded model IDs | Environment variable | | Expensive output | Minimize max_tokens | | No streaming | Always stream for UI | | Unnecessary PII | Redact before sending |

Output

All ten pitfalls checked against your codebase
max_tokens present on every messages.create call
System prompt using top-level system parameter
Messages strictly alternating user/assistant
stop_reason checked for truncation
Client instance reused across requests

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | API Error | Check error type and status code | See clade-common-errors |

Examples

See ten numbered pitfall sections above, each with BAD/GOOD code comparisons. Quick Reference table at the end summarizes all fixes.

Resources

Prerequisites

Familiarity with the Anthropic Messages API
Active Claude integration to audit
Access to codebase for pattern review

Instructions

Step 1: Review the patterns below

Each section contains production-ready code examples. Copy and adapt them to your use case.

Step 2: Apply to your codebase

Integrate the patterns that match your requirements. Test each change individually.

Step 3: Verify

Run your test suite to confirm the integration works correctly.

Agent Skills: Anthropic Known Pitfalls

Install this agent skill to your local

Skill Files