🇺🇸English

Claude API - Structured Outputs & Error Prevention Guide

Package : @anthropic-ai/sdk@0.71.2 Breaking Changes : Oct 2025 - Claude 3.5/3.7 models retired, Nov 2025 - Structured outputs beta Last Updated : 2026-01-09

What's New in v0.69.0+ (Nov 2025)

Major Features:

1. Structured Outputs (v0.69.0, Nov 14, 2025) - CRITICAL ⭐

Guaranteed JSON schema conformance - Claude's responses strictly follow your JSON schema with two modes.

⚠️ ACCURACY CAVEAT : Structured outputs guarantee format compliance, NOT accuracy. Models can still hallucinate—you get "perfectly formatted incorrect answers." Always validate semantic correctness (see below).

JSON Outputs (output_format) - For data extraction and formatting:

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Extract contact info: John Doe, john@example.com, 555-1234' }],
  betas: ['structured-outputs-2025-11-13'],
  output_format: {
    type: 'json_schema',
    json_schema: {
      name: 'Contact',
      strict: true,
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          email: { type: 'string' },
          phone: { type: 'string' }
        },
        required: ['name', 'email', 'phone'],
        additionalProperties: false
      }
    }
  }
});

// Guaranteed valid JSON matching schema
const contact = JSON.parse(message.content[0].text);
console.log(contact.name); // "John Doe"

Strict Tool Use (strict: true) - For validated function parameters:

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Get weather for San Francisco' }],
  betas: ['structured-outputs-2025-11-13'],
  tools: [{
    name: 'get_weather',
    description: 'Get current weather',
    input_schema: {
      type: 'object',
      properties: {
        location: { type: 'string' },
        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
      },
      required: ['location'],
      additionalProperties: false
    },
    strict: true  // ← Guarantees schema compliance
  }]
});

Requirements:

• Beta header : structured-outputs-2025-11-13 (via betas array)
• Models : Claude Opus 4.5, Claude Sonnet 4.5, Claude Opus 4 (best models only)
• SDK : v0.69.0+ required

Limitations:

• ❌ No recursive schemas
• ❌ No numerical constraints (minimum, maximum)
• ❌ Limited regex support (no backreferences/lookahead)
• ❌ Incompatible with citations and message prefilling
• ⚠️ Grammar compilation adds latency on first request (cached 24hrs)

Performance Characteristics:

• First request : +200-500ms latency for grammar compilation
• Subsequent requests : Normal latency (grammar cached for 24 hours)
• Cache sharing : Only with IDENTICAL schemas (small changes = recompilation)

Pre-warming critical schemas:

// Pre-compile schemas during server startup
const warmupMessage = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 10,
  messages: [{ role: 'user', content: 'warmup' }],
  betas: ['structured-outputs-2025-11-13'],
  output_format: {
    type: 'json_schema',
    json_schema: YOUR_CRITICAL_SCHEMA
  }
});
// Later requests use cached grammar

Semantic Validation (CRITICAL):

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  messages: [{ role: 'user', content: 'Extract contact: John Doe' }],
  betas: ['structured-outputs-2025-11-13'],
  output_format: {
    type: 'json_schema',
    json_schema: contactSchema
  }
});

const contact = JSON.parse(message.content[0].text);

// ✅ Format is guaranteed valid
// ❌ Content may be hallucinated

// ALWAYS validate semantic correctness
if (!isValidEmail(contact.email)) {
  throw new Error('Hallucinated email detected');
}
if (contact.age < 0 || contact.age > 120) {
  throw new Error('Implausible age value');
}

When to Use:

• Data extraction from unstructured text
• API response formatting
• Agentic workflows requiring validated tool inputs
• Eliminating JSON parse errors

⚠️ SDK v0.71.1+ Deprecation : Direct .parsed property access is deprecated. Check SDK docs for updated API.

2. Model Changes (Oct 2025) - BREAKING

Retired (return errors):

• ❌ Claude 3.5 Sonnet (all versions)
• ❌ Claude 3.7 Sonnet - DEPRECATED (Oct 28, 2025)

Active Models (Jan 2026):

Note : Claude 3.x models (3.5 Sonnet, 3.7 Sonnet, etc.) are deprecated. Use Claude 4.x+ models.

3. Context Management (Oct 28, 2025)

Clear Thinking Blocks - Automatic thinking block cleanup:

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 4096,
  messages: [{ role: 'user', content: 'Solve complex problem' }],
  betas: ['clear_thinking_20251015']
});
// Thinking blocks automatically managed

4. Agent Skills API (Oct 16, 2025)

Pre-built skills for Office files (PowerPoint, Excel, Word, PDF):

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Analyze this spreadsheet' }],
  betas: ['skills-2025-10-02'],
  // Requires code execution tool enabled
});

📚 Docs : https://platform.claude.com/docs/en/build-with-claude/structured-outputs

Streaming Responses (SSE)

CRITICAL Error Pattern - Errors occur AFTER initial 200 response:

const stream = anthropic.messages.stream({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }],
});

stream
  .on('error', (error) => {
    // Error can occur AFTER stream starts
    console.error('Stream error:', error);
    // Implement fallback or retry logic
  })
  .on('abort', (error) => {
    console.warn('Stream aborted:', error);
  });

Why this matters : Unlike regular HTTP errors, SSE errors happen mid-stream after 200 OK, requiring error event listeners

Prompt Caching (⭐ 90% Cost Savings)

CRITICAL Rule - cache_control MUST be on LAST block:

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: 'System instructions...',
    },
    {
      type: 'text',
      text: LARGE_CODEBASE, // 50k tokens
      cache_control: { type: 'ephemeral' }, // ← MUST be on LAST block
    },
  ],
  messages: [{ role: 'user', content: 'Explain auth module' }],
});

// Monitor cache usage
console.log('Cache reads:', message.usage.cache_read_input_tokens);
console.log('Cache writes:', message.usage.cache_creation_input_tokens);

Minimum requirements:

• Claude Sonnet 4.5: 1,024 tokens minimum
• Claude Haiku 4.5: 2,048 tokens minimum
• 5-minute TTL (refreshes on each use)
• Cache shared only with IDENTICAL content

⚠️ AWS Bedrock Limitation : Prompt caching does NOT work for Claude 4 family on AWS Bedrock (works for Claude 3.7 Sonnet only). Use direct Anthropic API for Claude 4 caching support. (GitHub Issue #1347)

Tool Use (Function Calling)

CRITICAL Patterns:

Strict Tool Use (with structured outputs):

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  betas: ['structured-outputs-2025-11-13'],
  tools: [{
    name: 'get_weather',
    description: 'Get weather data',
    input_schema: {
      type: 'object',
      properties: {
        location: { type: 'string' },
        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
      },
      required: ['location'],
      additionalProperties: false
    },
    strict: true  // ← Guarantees schema compliance
  }],
  messages: [{ role: 'user', content: 'Weather in NYC?' }]
});

Tool Result Pattern - tool_use_id MUST match:

const toolResults = [];
for (const block of response.content) {
  if (block.type === 'tool_use') {
    const result = await executeToolFunction(block.name, block.input);

    toolResults.push({
      type: 'tool_result',
      tool_use_id: block.id,  // ← MUST match tool_use block id
      content: JSON.stringify(result),
    });
  }
}

messages.push({
  role: 'user',
  content: toolResults,
});

Error Handling - Handle tool execution failures:

try {
  const result = await executeToolFunction(block.name, block.input);
  toolResults.push({
    type: 'tool_result',
    tool_use_id: block.id,
    content: JSON.stringify(result),
  });
} catch (error) {
  // Return error to Claude for handling
  toolResults.push({
    type: 'tool_result',
    tool_use_id: block.id,
    is_error: true,
    content: `Tool execution failed: ${error.message}`,
  });
}

Content Sanitization - Handle Unicode edge cases:

// U+2028 (LINE SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR) cause JSON parse failures
function sanitizeToolResult(content: string): string {
  return content
    .replace(/\u2028/g, '\n') // LINE SEPARATOR → newline
    .replace(/\u2029/g, '\n'); // PARAGRAPH SEPARATOR → newline
}

const toolResult = {
  type: 'tool_result',
  tool_use_id: block.id,
  content: sanitizeToolResult(result) // Sanitize before sending
};

(GitHub Issue #882)

Vision (Image Understanding)

CRITICAL Rules:

• Formats : JPEG, PNG, WebP, GIF (non-animated)
• Max size : 5MB per image
• Base64 overhead : ~33% size increase
• Context impact : Images count toward token limit
• Caching : Consider for repeated image analysis

Format validation - Check before encoding:

const validFormats = ['image/jpeg', 'image/png', 'image/webp', 'image/gif'];
if (!validFormats.includes(mimeType)) {
  throw new Error(`Unsupported format: ${mimeType}`);
}

Extended Thinking Mode

⚠️ Model Compatibility:

• ❌ Claude 3.7 Sonnet - DEPRECATED (Oct 28, 2025)
• ❌ Claude 3.5 Sonnet - RETIRED (not supported)
• ✅ Claude Opus 4.5 - Extended thinking supported (flagship)
• ✅ Claude Sonnet 4.5 - Extended thinking supported
• ✅ Claude Opus 4 - Extended thinking supported

CRITICAL:

• Thinking blocks are NOT cacheable
• Requires higher max_tokens (thinking consumes tokens)
• Check model before expecting thinking blocks

Rate Limits

CRITICAL Pattern - Respect retry-after header with exponential backoff:

async function makeRequestWithRetry(
  requestFn: () => Promise<any>,
  maxRetries = 3,
  baseDelay = 1000
): Promise<any> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.status === 429) {
        // CRITICAL: Use retry-after header if present
        const retryAfter = error.response?.headers?.['retry-after'];
        const delay = retryAfter
          ? parseInt(retryAfter) * 1000
          : baseDelay * Math.pow(2, attempt);

        console.warn(`Rate limited. Retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

Rate limit headers:

• anthropic-ratelimit-requests-limit - Total RPM allowed
• anthropic-ratelimit-requests-remaining - Remaining requests
• anthropic-ratelimit-requests-reset - Reset timestamp

Error Handling

Common Error Codes:

CRITICAL:

• Streaming errors occur AFTER initial 200 response
• Always implement error event listeners for streams
• Respect retry-after header on 429 errors
• Have fallback strategies for critical operations

Known Issues Prevention

This skill prevents 16 documented issues:

Issue #1: Rate Limit 429 Errors Without Backoff

Error : 429 Too Many Requests: Number of request tokens has exceeded your per-minute rate limit Source : https://docs.claude.com/en/api/errors Why It Happens : Exceeding RPM, TPM, or daily token limits Prevention : Implement exponential backoff with retry-after header respect

Issue #2: Streaming SSE Parsing Errors

Error : Incomplete chunks, malformed SSE events Source : Common SDK issue (GitHub #323) Why It Happens : Network interruptions, improper event parsing Prevention : Use SDK stream helpers, implement error event listeners

Issue #3: Prompt Caching Not Activating

Error : High costs despite cache_control blocks Source : https://platform.claude.com/docs/en/build-with-claude/prompt-caching Why It Happens : cache_control placed incorrectly (must be at END) Prevention : Always place cache_control on LAST block of cacheable content

Issue #4: Tool Use Response Format Errors

Error : invalid_request_error: tools[0].input_schema is invalid Source : API validation errors Why It Happens : Invalid JSON Schema, missing required fields Prevention : Validate schemas with JSON Schema validator, test thoroughly

Issue #5: Vision Image Format Issues

Error : invalid_request_error: image source must be base64 or url Source : API documentation Why It Happens : Incorrect encoding, unsupported formats Prevention : Validate format (JPEG/PNG/WebP/GIF), proper base64 encoding

Issue #6: Token Counting Mismatches for Billing

Error : Unexpected high costs, context window exceeded Source : Token counting differences Why It Happens : Not accounting for special tokens, formatting Prevention : Use official token counter, monitor usage headers

Issue #7: System Prompt Ordering Issues

Error : System prompt ignored or overridden Source : API behavior Why It Happens : System prompt placed after messages array Prevention : ALWAYS place system prompt before messages

Issue #8: Context Window Exceeded (200k)

Error : invalid_request_error: messages: too many tokens Source : Model limits Why It Happens : Long conversations without pruning Prevention : Implement message history pruning, use caching

Issue #9: Extended Thinking on Wrong Model

Error : No thinking blocks in response Source : Model capabilities Why It Happens : Using retired/deprecated models (3.5/3.7 Sonnet) Prevention : Only use extended thinking with Claude Opus 4.5, Claude Sonnet 4.5, or Claude Opus 4

Issue #10: API Key Exposure in Client Code

Error : CORS errors, security vulnerability Source : Security best practices Why It Happens : Making API calls from browser Prevention : Server-side only, use environment variables

Issue #11: Rate Limit Tier Confusion

Error : Lower limits than expected Source : Account tier system Why It Happens : Not understanding tier progression Prevention : Check Console for current tier, auto-scales with usage

Issue #12: Message Batches Beta Headers Missing

Error : invalid_request_error: unknown parameter: batches Source : Beta API requirements Why It Happens : Missing anthropic-beta header Prevention : Include anthropic-beta: message-batches-2024-09-24 header

Issue #13: Stream Errors Not Catchable with .withResponse() (Fixed in v0.71.2)

Error : Unhandled promise rejection when using messages.stream().withResponse() Source : GitHub Issue #856 Why It Happens : SDK internal error handling prevented user catch blocks from working (pre-v0.71.2) Prevention : Upgrade to v0.71.2+ or use event listeners instead

Fixed in v0.71.2+ :

try {
  const stream = await anthropic.messages.stream({
    model: 'claude-sonnet-4-5-20250929',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello' }]
  }).withResponse();
} catch (error) {
  // Now properly catchable in v0.71.2+
  console.error('Stream error:', error);
}

Workaround for pre-v0.71.2 :

const stream = anthropic.messages.stream({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }]
});

stream.on('error', (error) => {
  console.error('Stream error:', error);
});

Issue #14: MCP Tool Connections Cause 2-Minute Timeout

Error : Connection error / 499 Client disconnected after ~121 seconds Source : GitHub Issue #842 Why It Happens : MCP server connection management conflicts with long-running requests, even when MCP tools are not actively used Prevention : Use direct toolRunner instead of MCP for requests >2 minutes

Symptoms :

• Request works fine without MCP
• Fails at exactly ~121 seconds with MCP registered
• Dashboard shows: "Client disconnected (code 499)"
• Multiple users confirmed across streaming and non-streaming

Workaround :

// Don't use MCP for long requests
const message = await anthropic.beta.messages.toolRunner({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 4096,
  messages: [{ role: 'user', content: 'Long task >2 min' }],
  tools: [customTools] // Direct tool definitions, not MCP
});

Note : This is a known limitation with no official fix. Consider architecture changes if long-running requests with tools are required.

Issue #15: Structured Outputs Hallucination Risk

Error : Valid JSON format but incorrect/hallucinated content Source : Structured Outputs Docs Why It Happens : Structured outputs guarantee format compliance, NOT accuracy Prevention : Always validate semantic correctness, not just format

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  messages: [{ role: 'user', content: 'Extract contact: John Doe' }],
  betas: ['structured-outputs-2025-11-13'],
  output_format: {
    type: 'json_schema',
    json_schema: contactSchema
  }
});

const contact = JSON.parse(message.content[0].text);

// ✅ Format is guaranteed valid
// ❌ Content may be hallucinated

// CRITICAL: Validate semantic correctness
if (!isValidEmail(contact.email)) {
  throw new Error('Hallucinated email detected');
}
if (contact.age < 0 || contact.age > 120) {
  throw new Error('Implausible age value');
}

Issue #16: U+2028 Line Separator in Tool Results (Community-sourced)

Error : JSON parsing failures or silent errors when tool results contain U+2028 Source : GitHub Issue #882 Why It Happens : U+2028 is valid in JSON but not in JavaScript string literals Prevention : Sanitize tool results before passing to SDK

function sanitizeToolResult(content: string): string {
  return content
    .replace(/\u2028/g, '\n') // LINE SEPARATOR → newline
    .replace(/\u2029/g, '\n'); // PARAGRAPH SEPARATOR → newline
}

const toolResult = {
  type: 'tool_result',
  tool_use_id: block.id,
  content: sanitizeToolResult(result)
};

Official Documentation

• Claude API : https://platform.claude.com/docs/en/api
• Messages API : https://platform.claude.com/docs/en/api/messages
• Structured Outputs : https://platform.claude.com/docs/en/build-with-claude/structured-outputs
• Prompt Caching : https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• Tool Use : https://platform.claude.com/docs/en/build-with-claude/tool-use
• Vision : https://platform.claude.com/docs/en/build-with-claude/vision
• Rate Limits : https://platform.claude.com/docs/en/api/rate-limits
• Errors : https://platform.claude.com/docs/en/api/errors
• TypeScript SDK : https://github.com/anthropics/anthropic-sdk-typescript
• Context7 Library ID : /anthropics/anthropic-sdk-typescript

Package Versions

Latest : @anthropic-ai/sdk@0.71.2

{
  "dependencies": {
    "@anthropic-ai/sdk": "^0.71.2"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.3.0",
    "zod": "^3.23.0"
  }
}

Token Efficiency :

• Without skill : ~8,000 tokens (basic setup, streaming, caching, tools, vision, errors)
• With skill : ~4,200 tokens (knowledge gaps + error prevention + critical patterns)
• Savings : ~48% (~3,800 tokens)

Errors prevented : 16 documented issues with exact solutions Key value : Structured outputs (v0.69.0+), model deprecations (Oct 2025), prompt caching edge cases, streaming error patterns, rate limit retry logic, MCP timeout workarounds, hallucination validation

Last verified : 2026-01-20 | Skill version : 2.2.0 | Changes : Added 4 new issues from community research: streaming error handling (fixed in v0.71.2), MCP timeout workaround, structured outputs hallucination validation, U+2028 sanitization; expanded structured outputs section with performance characteristics and accuracy caveats; added AWS Bedrock caching limitation

Weekly Installs

325

Repository

jezweb/claude-skills

GitHub Stars

643

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubFailSocketPassSnykWarn

Installed on

claude-code275

opencode217

gemini-cli217

cursor208

antigravity198

codex190