Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/clade-known-pitfalls/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill clade-known-pitfalls. Copyright stays with the author (MIT).

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

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

Examples

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

Resources

• API Reference
• Best Practices

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.