clade-known-pitfalls

# 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. ```typescript // 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. ```typescript // 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. ```typescript // 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_token...