Claude API + Express.js - Production Integration Guide

Dependencies That Actually Matter

Every Express + Claude tutorial uses JavaScript. Don't. TypeScript will save your ass when you're debugging why response.content[0].text is undefined at 2am on a Saturday because your users decided that's the perfect time to break shit. Claude's response objects are nested like a fucking Russian doll - without types, you'll spend 3 hours in the VS Code debugger figuring out if it's content.text, message.content, or response.message.content[0].text.value or some other bullshit structure that changes based on what model you're hitting.

The dependency versions matter more than you'd think. Anthropic SDK 0.29.0 fixed a streaming memory leak that took down our staging server for 2 hours on a Thursday morning while the CEO was demoing to investors. Express 4.21.0 patches CVE-2024-27982 and two other security holes that script kiddies love to exploit. Don't use anything older than these versions in production unless you enjoy explaining security breaches to your boss.

Essential Dependencies:

{
  "dependencies": {
    "@anthropic-ai/sdk": "^0.29.0",
    "express": "^4.21.0",
    "helmet": "^8.0.0",
    "express-rate-limit": "^7.4.1",
    "cors": "^2.8.5",
    "express-validator": "^7.2.0"
  },
  "devDependencies": {
    "@types/express": "^4.17.21",
    "@types/cors": "^2.8.17",
    "typescript": "^5.6.0",
    "nodemon": "^3.1.4"
  }
}

Don't build your own HTTP client. The official SDK handles all the shit you'll forget: retry logic when Claude's servers hiccup, proper error parsing so you don't get cryptic 400s, and streaming that won't eat your memory. I wasted 2 weeks building a custom client that the SDK did better.

Authentication and API Key Management

API key management will destroy your budget if you screw it up. Junior dev on my team committed his key to a public repo at 11:30pm on a Friday night. Woke up Saturday morning to a $2,400 bill - some crypto asshole was using our API to generate trading signals for his shitcoin pump-and-dump scheme. GitHub's secret scanning caught it 8 hours too late, right after the automated email notifications started flooding my inbox.

Set billing alerts at $20, $50, $100. Trust me on this one. Environment variables aren't enough - someone will still console.log(process.env.ANTHROPIC_API_KEY) and commit it because they were debugging auth issues. Use .env files locally, AWS Secrets Manager in production, and pray your team reads the security docs.

Environment Configuration:

// config/environment.ts
export const config = {
  anthropic: {
    apiKey: process.env.ANTHROPIC_API_KEY,
    baseURL: process.env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com'
  },
  server: {
    port: process.env.PORT || 3000,
    nodeEnv: process.env.NODE_ENV || 'development'
  }
};

if (!config.anthropic.apiKey) {
  throw new Error('ANTHROPIC_API_KEY environment variable is required');
}

// Check API key format early - Claude will just say "invalid" without this
if (!config.anthropic.apiKey.startsWith('sk-ant-')) {
  throw new Error('Invalid ANTHROPIC_API_KEY format - should start with sk-ant-');
}

Client Initialization:

// services/claude.ts
import Anthropic from '@anthropic-ai/sdk';
import { config } from '../config/environment';

export const claude = new Anthropic({
  apiKey: config.anthropic.apiKey,
  maxRetries: 3,
  timeout: 60000 // Claude takes forever on complex requests
});

// Test connection at startup so you know immediately if keys are fucked
export async function validateConnection() {
  try {
    await claude.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 10,
      messages: [{ role: 'user', content: 'test' }]
    });
    console.log('✓ Claude API connection validated');
  } catch (error) {
    console.error('✗ Claude API connection failed:', error.message);
    process.exit(1); // Kill the server if Claude isn't working
  }
}

Express Application Structure

Middleware order will fuck you up every single time. CORS first, then rate limiting, then auth. Get it wrong and you'll spend 4 hours on a Tuesday afternoon debugging why POST requests work in Postman but return 401s from your React frontend, only to realize you put the auth middleware before CORS and it's rejecting preflight requests.

That 10MB JSON limit? Claude responses are massive when you ask it to analyze code or write documentation. Hit a complex request without it and you get PayloadTooLargeError: request entity too large - learned that one at 1:30am debugging a customer's 8MB response that contained their entire codebase analysis. Bumped it to 10MB and it worked perfectly.

Core Application Setup:

// app.ts
import express from 'express';
import helmet from 'helmet';
import cors from 'cors';
import rateLimit from 'express-rate-limit';
import { errorHandler } from './middleware/errorHandler';
import { claudeRoutes } from './routes/claude';

const app = express();

// Security middleware
app.use(helmet());
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || 'http://localhost:3000',
  credentials: true
}));

// Rate limiting - Claude's limits will destroy you if you're not careful
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // Conservative - new Claude accounts get 5 RPM, you'll hit it fast
  message: 'Too many requests from this IP, please try again later',
  standardHeaders: true, // Return rate limit info in headers
  legacyHeaders: false // Disable X-RateLimit-* headers
});

app.use(limiter);
app.use(express.json({ limit: '10mb' }));

// Routes
app.use('/api/claude', claudeRoutes);

// Error handling
app.use(errorHandler);

export { app };

Message Processing and Streaming

Streaming is a fucking nightmare. The Anthropic docs make it look easy with their cute 10-line examples, but don't mention client disconnects mid-stream, malformed UTF-8 chunks that crash your JSON parser, or memory leaks when streams don't close properly. I watched a streaming bug take down production for 90 minutes because it didn't handle users closing their browser tabs - Node.js kept writing to dead connections until it exhausted file descriptors and the whole process crashed with EMFILE: too many open files.

This code handles all the bullshit that breaks in production and ruins your weekend.

Standard Message Processing:

// services/messageProcessor.ts
import { claude } from './claude';
import { MessageCreateParams } from '@anthropic-ai/sdk/resources/messages';

export class MessageProcessor {
  async processMessage(params: MessageCreateParams) {
    try {
      const response = await claude.messages.create({
        model: 'claude-sonnet-4-20250514',
        max_tokens: 4096,
        ...params
      });

      return {
        content: response.content,
        usage: response.usage,
        role: response.role,
        requestId: response._request_id
      };
    } catch (error) {
      if (error instanceof Anthropic.APIError) {
        // The "model_not_found" error everyone hits
        if (error.status === 400 && error.message.includes('model_not_found')) {
          throw new ClaudeAPIError(400, 'Invalid model specified. Check model name spelling.');
        }
        throw new ClaudeAPIError(error.status, error.message);
      }
      throw error;
    }
  }
}

Streaming Implementation:

// routes/claude.ts
import { Router } from 'express';
import { MessageProcessor } from '../services/messageProcessor';

const router = Router();
const messageProcessor = new MessageProcessor();

router.post('/stream', async (req, res) => {
  // Handle client disconnect or your memory will leak like crazy
  const cleanup = () => {
    if (!res.headersSent) res.status(499).end();
  };
  req.on('close', cleanup);
  req.on('aborted', cleanup);

  try {
    res.setHeader('Content-Type', 'text/event-stream');
    res.setHeader('Cache-Control', 'no-cache');
    res.setHeader('Connection', 'keep-alive');
    res.setHeader('Access-Control-Allow-Origin', '*'); // Streaming breaks without this

    const stream = await claude.messages.create({
      ...req.body,
      stream: true
    });

    for await (const chunk of stream) {
      // Bail if user closed their browser
      if (req.destroyed) break;
      
      if (chunk.type === 'content_block_delta') {
        res.write(`data: ${JSON.stringify(chunk.delta)}

`);
      }
    }

    if (!req.destroyed) {
      res.write('data: [DONE]

');
      res.end();
    }
  } catch (error) {
    if (!req.destroyed) {
      res.write(`data: ${JSON.stringify({ error: error.message })}

`);
      res.end();
    }
  }
});

export { router as claudeRoutes };

Request Validation and Sanitization

Input validation saves your sanity. Claude gives cryptic "invalid request format" errors without it. You'll waste hours debugging requests that look fine to you.

The model name validation prevents the typo everyone makes - "claude-3-sonnet" instead of "claude-sonnet-4-20250514". Spent 45 minutes on this exact bug last month.

// middleware/validation.ts
import { body, validationResult } from 'express-validator';
import { Request, Response, NextFunction } from 'express';

export const validateMessageRequest = [
  body('messages')
    .isArray()
    .withMessage('Messages must be an array')
    .notEmpty()
    .withMessage('Messages array cannot be empty'),
  
  body('messages.*.role')
    .isIn(['user', 'assistant'])
    .withMessage('Message role must be user or assistant'),
  
  body('messages.*.content')
    .trim()
    .isLength({ min: 1, max: 100000 })
    .withMessage('Message content must be between 1 and 100,000 characters'),
  
  body('model')
    .optional()
    .isIn(['claude-sonnet-4-20250514', 'claude-haiku-3-20241022', 'claude-opus-3-20241022'])
    .withMessage('Invalid model - use claude-sonnet-4-20250514, claude-haiku-3-20241022, or claude-opus-3-20241022'),
  
  body('max_tokens')
    .optional()
    .isInt({ min: 1, max: 8192 })
    .withMessage('max_tokens must be between 1 and 8192'),

  (req: Request, res: Response, next: NextFunction) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({
        error: 'Validation failed',
        details: errors.array()
      });
    }
    next();
  }
];

This setup prevents the disasters everyone hits: leaked keys bankrupting you, memory leaks crashing servers, typos breaking integrations, and validation failures confusing users.

Get this foundation solid before adding fancy shit like Prometheus metrics or Docker. The basics aren't sexy but they prevent 3am pages from angry customers.

Error Handling (Because Everything Will Fail)

Every tutorial stops at "hello world" and ignores what happens when Claude's servers shit the bed at 2pm on Black Friday. Claude doesn't just return clean 500 errors - it gives you cryptic messages like anthropic_api_error: invalid_request_format that mean absolutely nothing to your users and tell you fuck-all about what went wrong.

Rate limits hit with zero warning at exactly the worst moment. Auth fails randomly with invalid_api_key even though you've been using the same key for weeks. Requests timeout after users wait 45 seconds watching your loading spinner, then they get pissed and email support. Your generic error handler returning "something went wrong" makes users think your app is broken shit built by incompetent developers.

Centralized Error Handler:

// middleware/errorHandler.ts
import { Request, Response, NextFunction } from 'express';
import Anthropic from '@anthropic-ai/sdk';

export class ClaudeAPIError extends Error {
  constructor(
    public statusCode: number,
    message: string,
    public requestId?: string,
    public anthropicError?: boolean
  ) {
    super(message);
    this.name = 'ClaudeAPIError';
  }
}

export const errorHandler = (
  error: Error,
  req: Request,
  res: Response,
  next: NextFunction
) => {
  console.error('API Error:', {
    error: error.message,
    stack: error.stack,
    url: req.url,
    method: req.method,
    timestamp: new Date().toISOString()
  });

  if (error instanceof Anthropic.APIError) {
    // Turn Claude's garbage errors into something users understand
    let userMessage = sanitizeErrorMessage(error.message);
    
    if (error.status === 429) {
      userMessage = 'Claude API rate limit exceeded. Please wait a minute before trying again.';
    } else if (error.status === 400 && error.message.includes('max_tokens')) {
      userMessage = 'Response too long. Try reducing your request complexity.';
    } else if (error.status === 500) {
      userMessage = 'Claude API is temporarily unavailable. Please try again in a few minutes.';
    }
    
    return res.status(error.status).json({
      error: 'Claude API Error',
      message: userMessage,
      requestId: error.request_id,
      timestamp: new Date().toISOString()
    });
  }

  if (error instanceof ClaudeAPIError) {
    return res.status(error.statusCode).json({
      error: 'Integration Error',
      message: error.message,
      requestId: error.requestId,
      timestamp: new Date().toISOString()
    });
  }

  // Default error response
  res.status(500).json({
    error: 'Internal Server Error',
    message: 'An unexpected error occurred',
    timestamp: new Date().toISOString()
  });
};

function sanitizeErrorMessage(message: string): string {
  // Strip out API keys because developers are idiots
  return message.replace(/api[_-]?key[s]?[
s:=]["']?[\w-]+/gi, 'API_KEY_REDACTED');
}

Advanced Rate Limiting Strategies

Single rate limit for everything? You're absolutely fucked. Claude's got different limits for different models - Sonnet gets 5 RPM on new accounts, Haiku gets 25 RPM, and Opus gets 2 RPM because it's slow as molasses. Hit the global limit and your entire app dies with 429 Too Many Requests errors. Our product demo got hammered during a conference and nobody could use the app for 4 hours while I frantically tried to figure out why perfectly valid requests were failing.

You need layers: basic flood protection to stop script kiddies, Claude-specific limits that match their bullshit tier system, and sketchy behavior detection for users trying to mine crypto with your API. Without Redis, your rate limiting is completely useless at scale - learned that lesson when our single-server rate limiter reset every time we deployed and users could spam requests during the 30-second deployment window.

Multi-Tier Rate Limiting:

// middleware/rateLimiter.ts
import rateLimit from 'express-rate-limit';
import RedisStore from 'rate-limit-redis';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL || 'redis://localhost:6379');

// General API rate limiting
export const generalLimiter = rateLimit({
  store: new RedisStore({
    storeClient: redis,
    prefix: 'rl:general:'
  }),
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 1000, // 1000 requests per 15 minutes
  message: {
    error: 'Too many requests',
    retryAfter: '15 minutes'
  }
});

// Claude-specific limits (way more restrictive)
export const claudeLimiter = rateLimit({
  store: new RedisStore({
    storeClient: redis,
    prefix: 'rl:claude:'
  }),
  windowMs: 60 * 1000, // 1 minute
  max: 10, // New Claude accounts get 5 RPM - you'll hit this instantly
  message: {
    error: 'Claude API rate limit exceeded',
    retryAfter: '1 minute',
    hint: 'New Anthropic accounts have strict rate limits - upgrade for higher throughput'
  },
  // Let premium users skip the pain
  skip: (req) => {
    return req.headers['x-user-tier'] === 'premium';
  }
});

// IP-based suspicious activity detection
export const suspiciousActivityLimiter = rateLimit({
  store: new RedisStore({
    storeClient: redis,
    prefix: 'rl:suspicious:'
  }),
  windowMs: 60 * 60 * 1000, // 1 hour
  max: 5000, // Very high limit
  skip: (req) => {
    // Whitelist your office IPs so you don't rate limit yourself during demos
    const trustedIPs = process.env.TRUSTED_IPS?.split(',') || [];
    return trustedIPs.includes(req.ip);
  }
});

Authentication and Authorization Middleware

Auth middleware looks trivial until you deploy and realize you've built a security disaster that would make OWASP weep. I've seen production apps that check API keys but ignore JWT expiration dates - users with 6-month-old tokens still accessing paid features. Systems that accept any Bearer token that vaguely looks like JWT without verifying the signature, because someone commented out the validation "temporarily" during debugging and forgot to uncomment it.

This pattern handles the common auth cases without the obvious security holes that get you fired. API key first (for bots and services), JWT second (for actual users). Both strategies work in production, neither will get you pwned by someone who found your API docs on a Tuesday.

Multi-Strategy Authentication:

// middleware/auth.ts
import { Request, Response, NextFunction } from 'express';
import jwt from 'jsonwebtoken';

interface AuthenticatedRequest extends Request {
  user?: {
    id: string;
    role: string;
    permissions: string[];
  };
  apiKey?: {
    keyId: string;
    permissions: string[];
  };
}

export const authenticate = async (
  req: AuthenticatedRequest,
  res: Response,
  next: NextFunction
) => {
  try {
    // Try API key authentication first
    const apiKey = req.headers['x-api-key'] as string;
    if (apiKey) {
      const keyData = await validateApiKey(apiKey);
      if (keyData) {
        req.apiKey = keyData;
        return next();
      }
    }

    // Try JWT authentication
    const token = req.headers.authorization?.replace('Bearer ', '');
    if (token) {
      const decoded = jwt.verify(token, process.env.JWT_SECRET!) as any;
      req.user = decoded;
      return next();
    }

    return res.status(401).json({
      error: 'Authentication required',
      message: 'Provide valid API key or JWT token'
    });
  } catch (error) {
    return res.status(401).json({
      error: 'Invalid authentication',
      message: 'Authentication token is invalid or expired'
    });
  }
};

export const requirePermission = (permission: string) => {
  return (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
    const userPermissions = req.user?.permissions || req.apiKey?.permissions || [];
    
    if (!userPermissions.includes(permission) && !userPermissions.includes('admin')) {
      return res.status(403).json({
        error: 'Insufficient permissions',
        required: permission,
        message: 'Your account lacks the required permissions for this operation'
      });
    }
    
    next();
  };
};

async function validateApiKey(key: string) {
  // Replace with your actual key validation
  // Database lookup, Redis cache, whatever
  return null; // TODO: implement this or everything breaks
}

Request Context and Correlation IDs

Request tracking saves your ass when debugging distributed failures. When Claude times out and your user complains, correlation IDs let you trace the exact request through logs instead of guessing.

Request Context Middleware:

// middleware/requestContext.ts
import { Request, Response, NextFunction } from 'express';
import { v4 as uuidv4 } from 'uuid';

export interface RequestContext {
  correlationId: string;
  userId?: string;
  apiKeyId?: string;
  startTime: Date;
  userAgent: string;
  ip: string;
}

declare global {
  namespace Express {
    interface Request {
      context: RequestContext;
    }
  }
}

export const requestContext = (req: Request, res: Response, next: NextFunction) => {
  const correlationId = (req.headers['x-correlation-id'] as string) || uuidv4();
  
  req.context = {
    correlationId,
    startTime: new Date(),
    userAgent: req.headers['user-agent'] || 'unknown',
    ip: req.ip || req.connection.remoteAddress || 'unknown'
  };

  // Send correlation ID back so users can reference it in support tickets
  res.setHeader('x-correlation-id', correlationId);
  
  // Log request start
  console.log('Request started:', {
    correlationId,
    method: req.method,
    url: req.url,
    userAgent: req.context.userAgent,
    ip: req.context.ip
  });

  // Log request completion
  res.on('finish', () => {
    const duration = Date.now() - req.context.startTime.getTime();
    console.log('Request completed:', {
      correlationId,
      method: req.method,
      url: req.url,
      statusCode: res.statusCode,
      duration: `${duration}ms`
    });
  });

  next();
};

Content Filtering and Safety

Content filtering prevents users from turning your Claude integration into a malware generator or prompt injection playground. Claude's safety filters aren't perfect and won't catch everything malicious users try - I've seen jailbreak attempts slip through that would make your security team shit bricks.

Users will attempt to generate viruses, extract training data, create fake news, bypass your business logic, and social engineer Claude into doing things it shouldn't. Basic keyword filtering stops the dumb shit like "create virus plz". The sneaky attempts - like encoding malicious prompts in base64 or using unicode tricks - need actual effort to catch.

Content Safety Middleware:

// middleware/contentSafety.ts
import { Request, Response, NextFunction } from 'express';

const BLOCKED_PATTERNS = [
  /generate\s+malware/i,
  /create\s+virus/i,
  /hack\s+into/i,
  /bypass\s+security/i,
  /jailbreak/i,
  /ignore\s+(previous|above)\s+instructions/i,
  // Common prompt injection bullshit
  /pretend\s+you\s+are/i,
  /roleplay\s+as/i
];

const SENSITIVE_TOPICS = [
  'personal_information',
  'medical_advice',
  'legal_advice',
  'financial_advice'
];

export const contentSafety = (req: Request, res: Response, next: NextFunction) => {
  const messages = req.body.messages || [];
  
  for (const message of messages) {
    if (typeof message.content === 'string') {
      // Scan for obvious bad shit
      for (const pattern of BLOCKED_PATTERNS) {
        if (pattern.test(message.content)) {
          return res.status(400).json({
            error: 'Content violation',
            message: 'Request contains prohibited content',
            code: 'CONTENT_BLOCKED'
          });
        }
      }

      // Stop people from sending war and peace
      if (message.content.length > 100000) {
        return res.status(400).json({
          error: 'Content too long',
          message: 'Message content exceeds maximum length',
          maxLength: 100000
        });
      }
    }
  }

  next();
};

This middleware isn't optional if real users touch your app. Every pattern here fixes a production disaster I've debugged: keys leaked to GitHub, rate limits killing apps, auth bypasses, malicious prompts.

Don't build everything at once. Error handling and rate limiting first - they prevent 80% of disasters. Auth and content filtering before you launch. Fancy monitoring later when you have traffic worth monitoring.

Build this foundation or spend your nights explaining to angry users why everything's broken.