Anthropic Known Pitfalls

Overview

Ten common mistakes when building with the Anthropic API and how to avoid them: forgetting

max_tokens

stop_reason

1. Forgetting

max_tokens

Unlike OpenAI,

max_tokens

// 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

// 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'

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

5. Creating Client Per Request

Each

new Anthropic()

// 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

max_tokens

system

stop_reason

max_tokens

max_tokens

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

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

• 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.