Anthropic TypeScript SDK: Production Implementation Guide

Overview

Official TypeScript client @anthropic-ai/sdk with 2M weekly downloads. Provides reliable Claude API access with proper streaming, type safety, and error handling.

Installation and Configuration

Basic Setup

npm install @anthropic-ai/sdk

Critical Configuration Order

// MUST call dotenv.config() BEFORE importing SDK
require('dotenv').config();
import Anthropic from '@anthropic-ai/sdk';

// This order WILL FAIL - env vars won't load
import Anthropic from '@anthropic-ai/sdk';
require('dotenv').config(); // Too late

Production Client Configuration

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  maxRetries: 5,
  timeout: 300000, // 5 minutes for large responses
  defaultHeaders: {
    'User-Agent': 'your-app/1.0.0'
  }
});

Critical Failure Modes and Solutions

Runtime Crashes

Problem: App crashes with "Cannot read property 'content' of undefined"
Cause: Claude returns empty responses, SDK doesn't handle gracefully
Solution: Use optional chaining

// WILL CRASH
console.log(message.content[0].text);

// SAFE
const text = message.content?.[0]?.text || "No response";

Authentication Failures

Problem: API key works in Postman but fails in code
Root Causes:

• Environment variables not loading
• Wrong variable name (must be ANTHROPIC_API_KEY)
• .env file in wrong location
  Debug: console.log('Key:', process.env.ANTHROPIC_API_KEY?.slice(0, 10))

Function Calling Errors

Problem: "Invalid tool use" with unclear error messages
Common Causes:

• Type mismatches: "type": "string" for numbers
• Missing required arrays in nested objects
• Tool description exceeds character limit
• Schema doesn't match function parameters
  Solution: Validate schemas with JSON Schema Validator before deployment

Memory Exhaustion

Problem: Apps crash with 500MB+ memory usage
Triggers: 100k+ token contexts, large responses
Platform Impact:

• Lambda: Kills processes at memory limits
• Edge functions: Out of memory errors
  Mitigation:
• Use Claude 3.5 instead of Claude 4 (significantly less memory)
• Stream responses instead of buffering
• Process documents in chunks
• Monitor with process.memoryUsage()

Platform-Specific Limitations

Streaming Timeouts

Platform	Timeout Limit	Impact
Vercel Edge Functions	25 seconds	Kills mid-response
Cloudflare Workers	30 seconds	Silent failures
AWS Lambda	Memory-based	500MB+ kills process
Railway	10 minutes	Generally reliable

Error Handling Strategy

import { RateLimitError, APIError } from '@anthropic-ai/sdk';

try {
  const message = await client.messages.create(params);
} catch (error) {
  if (error instanceof RateLimitError) {
    const retryAfter = error.headers['retry-after'] || 60;
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  } else if (error instanceof APIError) {
    // Save request ID for support tickets
    console.error('Request ID:', error.headers['request-id']);
  }
}

Rate Limiting and Cost Management

Rate Limit Progression

• New accounts: 50 RPM (severely limiting)
• After $100 spend: 500 RPM
• After $1000 spend: 2000 RPM
• Increase requests: 3-5 business days via support

Cost Optimization

Hidden cost factors:

• System prompts count as input tokens on every request
• Function schemas add ~500 tokens per call
• Claude 4 costs 5x more than Claude 3.5 for input tokens
• Long conversations accumulate token costs

Recommendation: Use Claude 3.5 for most tasks, Claude 4 only when advanced reasoning required

Streaming Implementation

Basic Streaming Setup

const stream = client.messages
  .stream({
    model: 'claude-3-5-sonnet-20240620',
    max_tokens: 2048,
    messages: [{ role: 'user', content: 'Write something long' }],
  })
  .on('text', (text) => {
    console.log(text);
  })
  .on('error', (error) => {
    if (error.code === 'ECONNRESET') {
      // Implement retry logic
    } else {
      throw error;
    }
  });

Stream Error Recovery

Network interruptions are common. Implement retry logic for ECONNRESET errors.

Model Management

Model Naming Strategy

Critical: Use specific versions, not generic names

• Use: claude-3-5-sonnet-20240620
• Avoid: claude-3-5-sonnet (subject to changes)
• Never use: claude-instant-1 (deprecated without notice)

Runtime Support

• Node 18+, Bun, Deno: Full support
• Cloudflare Workers: 10MB memory limit can be exceeded
• Browser: Requires dangerouslyAllowBrowser: true (security risk)

Comparison Matrix

Factor	Anthropic SDK	OpenAI SDK	LangChain	Vercel AI SDK
Reliability	Good	Good	Breaks frequently	UI-focused
Streaming	Server-Sent Events	Server-Sent Events	Connection drops	React optimized
Bundle Size	~2MB	~1.8MB	~15MB+	~600KB
Learning Curve	Low	Low	High	Medium
Function Calling	Native	N/A	Complex setup	Provider wrapper
Production Ready	Yes	Yes	Requires expertise	React apps only

Common Error Patterns

Network Errors

• ENOTFOUND api.anthropic.com: DNS resolution issues
• ECONNRESET: Connection dropped mid-stream
• Various 500 errors: Always includes request ID for support

Model Errors

• maximum tokens exceeded: Even with max_tokens set properly
• model not found: Models renamed without notice
• Empty responses: No error thrown, content array empty

Type Safety Issues

TypeScript types may not match runtime behavior. Add runtime checks:

if (response && 'stream' in response) {
  // Handle stream
} else {
  // Handle regular response
}

Resource Requirements

Time Investment

• Basic implementation: 30 minutes
• Production-ready setup: 2-4 hours
• Function calling integration: 2-8 hours depending on complexity

Expertise Requirements

• TypeScript knowledge: Required
• Streaming concepts: Helpful for real-time features
• Error handling patterns: Critical for production

Infrastructure Considerations

• Memory: 500MB+ for large contexts
• Network: Stable connection required for streaming
• Monitoring: Request ID tracking for support tickets

Critical Warnings

What Documentation Doesn't Tell You

• Rate limits are brutal for new accounts (50 RPM)
• Memory usage can spike unexpectedly with large responses
• Model names change without deprecation warnings
• Function calling has undocumented character limits
• Streaming can fail silently on certain platforms

Breaking Points

• 1000+ spans break UI debugging capabilities
• 100k+ tokens trigger memory issues
• Long conversations become cost-prohibitive
• Function schemas over character limits fail without clear errors

Production Readiness Checklist

• Implement proper error handling with request ID logging
• Set up monitoring for memory usage and response times
• Configure retry logic for network interruptions
• Pin specific model versions
• Implement cost tracking for token usage
• Test streaming on target deployment platform
• Validate function calling schemas before deployment