Anthropic Known Pitfalls
Pitfall 1: Wrong Import / Class Name
from anthropic import AnthropicClient
import anthropic
client = anthropic.Anthropic()
import { Anthropic } from '@anthropic-ai/sdk';
import Anthropic from '@anthropic-ai/sdk';
Pitfall 2: Forgetting max_tokens (Required)
msg = client.messages.create(
model="claude-sonnet-4-20250514",
messages=[{"role": "user", "content": "Hello"}]
)
msg = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}]
)
Pitfall 3: System Prompt in Messages Array
messages = [
{"role": "system", "content": "You are helpful."},
{"role": "user", "content": "Hello"}
]
msg = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
system="You are helpful.",
messages=[{"role": "user", "content": "Hello"}]
)
Pitfall 4: Accessing Response Wrong
text = response.choices[0].message.content
text = response.content[0].text
text_blocks = [b.text for b in response.content if b.type == "text"]
text = "\n".join(text_blocks)
Pitfall 5: Ignoring Stop Reason
text = msg.content[0].text
if msg.stop_reason == "max_tokens":
print("WARNING: Response was truncated. Increase max_tokens.")
elif msg.stop_reason == "tool_use":
print("Claude wants to call a tool — process tool_use blocks")
elif msg.stop_reason == "end_turn":
print("Complete response")
Pitfall 6: Not Handling tool_use_id Properly
tool_results = [{"type": "tool_result", "tool_use_id": "some-id", "content": "..."}]
for block in response.content:
if block.type == "tool_use":
result = execute_tool(block.name, block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": result
})
Pitfall 7: Hardcoding Model IDs Without Versioning
model = "claude-3-5-sonnet"
model = "claude-sonnet-4-20250514"
Pitfall 8: Not Using SDK Auto-Retry
for attempt in range(3):
try:
msg = client.messages.create(...)
break
except Exception:
time.sleep(2 ** attempt)
client = anthropic.Anthropic(max_retries=5)
msg = client.messages.create(...)
Pitfall 9: Inflated max_tokens
msg = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=200000,
messages=[{"role": "user", "content": "Classify: positive or negative?"}]
)
msg = client.messages.create(
model="claude-haiku-4-20250514",
max_tokens=16,
messages=[{"role": "user", "content": "Classify: positive or negative?"}]
)
Pitfall 10: No Cost Tracking
msg = client.messages.create(...)
cost = (msg.usage.input_tokens * 3.0 + msg.usage.output_tokens * 15.0) / 1_000_000
Quick Reference: Anthropic vs OpenAI Differences
| Feature | OpenAI | Anthropic |
|---|
max_tokens | Optional | Required |
| System prompt | In messages array | system parameter |
| Response text | .choices[0].message.content | .content[0].text |
| Default import | Named export | Default export |
| Auto-retry | No | Yes (configurable) |
| Streaming | Yields chunks | SSE events |
Resources
