claude-api

Claude API - 構造化出力とエラー防止ガイド

パッケージ: @anthropic-ai/[email protected] 破壊的変更: 2025年10月 - Claude 3.5／3.7 モデルの提供終了、2025年11月 - 構造化出力ベータ 最終更新日: 2026-01-09

---

v0.69.0 以降の新機能（2025年11月）

主な機能:

1. 構造化出力（v0.69.0、2025年11月14日）- 重要 ⭐

JSON スキーマへの準拠を保証 - Claude の応答が、2 つのモードで JSON スキーマに厳密に従います。

⚠️ 正確性に関する注意: 構造化出力が保証するのは形式への準拠であり、正確性ではありません。モデルは依然として幻覚を起こす可能性があり、「完璧な形式の誤った回答」が返されることもあります。必ず意味的な正確性を検証してください（下記参照）。

JSON 出力（output_format） - データの抽出と整形に使用します。

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, [email protected], 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: true） - 検証済みの関数パラメーターに使用します。

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
  }]
});

要件:

• ベータヘッダー: structured-outputs-2025-11-13（betas 配列経由）
• モデル: Claude Opus 4.5、Claude Sonnet 4.5、Claude Opus 4（上位モデルのみ）
• SDK: v0.69.0 以降が必要です

制限事項:

• ❌ 再帰スキーマには対応していません
• ❌ 数値制約（minimum、maximum）には対応していません
• ❌ 正規表現のサポートは限定的です（後方参照／先読みには対応していません）
• ❌ 引用およびメッセージのプレフィルには対応していません
• ⚠️ 文法のコンパイルにより、初回リクエストのレイテンシーが増加します（24 時間キャッシュされます）

パフォーマンス特性:

• 初回リクエスト: 文法のコンパイルにより、レイテンシーが 200～500ms 増加します
• 2 回目以降のリクエスト: 通常のレイテンシーです（文法は 24 時間キャッシュされます）
• キャッシュ共有: スキーマが完全に同一の場合のみ共有されます（わずかな変更でも再コンパイルされます）

重要なスキーマの事前ウォームアップ:

// 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

意味的検証（重要）:

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');
}

使用する場面:

• 非構造化テキストからのデータ抽出
• API 応答の整形
• 検証済みのツール入力を必要とするエージェントワークフロー
• JSON の解析エラーの解消

⚠️ SDK v0.71.1 以降の非推奨事項: .parsed プロパティへの直接アクセスは非推奨です。更新された API については SDK ドキュメントを確認してください。

2. モデルの変更（2025年10月）- 破壊的変更

提供終了（エラーが返されます）:

• ❌ Claude 3.5 Sonnet（すべてのバージョン）
• ❌ Claude 3.7 Sonnet - 非推奨（2025年10月28日）

アクティブなモデル（2026年1月）:

モデル	ID	コンテキスト	最適な用途	料金（MTok あたり）
Claude Opus 4.5	claude-opus-4-5-20251101	200k	フラッグシップ - 推論、コーディング、エージェントに最適	$5/$25（入力／出力）
Claude Sonnet 4.5	claude-sonnet-4-5-20250929	200k	バランスの取れたパフォーマンス	$3/$15（入力／出力）
Claude Opus 4	claude-opus-4-20250514	200k	高い能力	$15/$75
Claude Haiku 4.5	claude-haiku-4-5-20250929	200k	最先端に近い性能、高速	$1/$5

注: Claude 3.x モデル（3.5 Sonnet、3.7 Sonnet など）は非推奨です。Claude 4.x 以降のモデルを使用してください。

3. コンテキスト管理（2025年10月28日）

思考ブロックのクリア - 思考ブロックを自動的にクリーンアップします。

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（2025年10月16日）

Office ファイル（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
});

📚 ドキュメント: https://platform.claude.com/docs/en/build-with-claude/structured-outputs

---

ストリーミング応答（SSE）

重要なエラーパターン - エラーは最初の 200 応答の後に発生します。

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);
  });

重要な理由: 通常の HTTP エラーとは異なり、SSE エラーは 200 OK の後、ストリームの途中で発生するため、エラーイベントリスナーが必要です。

---

プロンプトキャッシュ（⭐ コストを 90% 削減）

重要なルール - cache_control は必ず最後のブロックに指定してください。

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);

最低要件:

• Claude Sonnet 4.5: 最低 1,024 トークン
• Claude Haiku 4.5: 最低 2,048 トークン
• TTL は 5 分（使用するたびに更新されます）
• キャッシュは内容が完全に同一の場合のみ共有されます

⚠️ AWS Bedrock の制限: AWS Bedrock では Claude 4 ファミリーのプロンプトキャッシュは機能しません（Claude 3.7 Sonnet では機能します）。Claude 4 のキャッシュ機能を使用するには、Anthropic API に直接接続してください。(GitHub Issue #1347)

---

ツールの使用（関数呼び出し）

重要なパターン：

厳密なツールの使用（構造化出力の場合）：

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_use_id は一致する必要があります：

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,
});

エラー処理 - ツール実行の失敗に対処します：

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}`,
  });
}

コンテンツのサニタイズ - Unicode のエッジケースに対処します：

// 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)

---

ビジョン（画像の理解）

重要なルール：

• 形式：JPEG、PNG、WebP、GIF（アニメーションなし）
• 最大サイズ：画像 1 枚あたり 5MB
• Base64 のオーバーヘッド：サイズが約 33% 増加します
• コンテキストへの影響：画像はトークン上限に含まれます
• キャッシュ：画像を繰り返し分析する場合は検討してください

形式の検証 - エンコード前に確認します：

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

---

拡張思考モード

⚠️ モデルの互換性：

• ❌ Claude 3.7 Sonnet - 非推奨（2025 年 10 月 28 日）
• ❌ Claude 3.5 Sonnet - 提供終了（サポート対象外）
• ✅ Claude Opus 4.5 - 拡張思考に対応（フラッグシップ）
• ✅ Claude Sonnet 4.5 - 拡張思考に対応
• ✅ Claude Opus 4 - 拡張思考に対応

重要：

• 思考ブロックはキャッシュできません
• より大きな max_tokens が必要です（思考にトークンを消費します）
• 思考ブロックを想定する前にモデルを確認してください

---

レート制限

重要なパターン - 指数バックオフを使用し、retry-after ヘッダーに従ってください：

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');
}

レート制限ヘッダー：

• anthropic-ratelimit-requests-limit - 許可される合計 RPM
• anthropic-ratelimit-requests-remaining - 残りのリクエスト数
• anthropic-ratelimit-requests-reset - リセット時刻

---

エラー処理

一般的なエラーコード：

ステータス	エラータイプ	原因	解決策
400	invalid_request_error	不正なパラメーター	リクエスト本文を検証します
401	authentication_error	無効な API キー	環境変数を確認します
403	permission_error	機能へのアクセス権がありません	アカウントのプランを確認します
404	not_found_error	無効なエンドポイント	API バージョンを確認します
429	rate_limit_error	リクエストが多すぎます	リトライ処理を実装します
500	api_error	内部エラー	バックオフを行って再試行します
529	overloaded_error	システムが過負荷です	後で再試行します

重要：

• ストリーミングのエラーは、最初の 200 レスポンスの後に発生します
• ストリームには必ずエラーイベントリスナーを実装してください
• 429 エラーでは retry-after ヘッダーに従ってください
• 重要な処理にはフォールバック戦略を用意してください

---

既知の問題の予防

このスキルは、文書化されている 16 件の問題を防止します：

問題 #1：バックオフなしで発生するレート制限 429 エラー

エラー：429 Too Many Requests: Number of request tokens has exceeded your per-minute rate limit ソース：https://docs.claude.com/en/api/errors 発生理由：RPM、TPM、または 1 日あたりのトークン上限を超過した場合 予防策：retry-after ヘッダーに従う指数バックオフを実装します

問題 #2：ストリーミング SSE の解析エラー

エラー：不完全なチャンク、不正な SSE イベント ソース：一般的な SDK の問題（GitHub #323） 発生理由：ネットワークの中断、不適切なイベント解析 予防策：SDK のストリームヘルパーを使用し、エラーイベントリスナーを実装します

問題 #3：プロンプトキャッシュが有効にならない

エラー：cache_control ブロックを設定しているのにコストが高い ソース：https://platform.claude.com/docs/en/build-with-claude/prompt-caching 発生理由：cache_control の配置が誤っている（最後に置く必要があります） 予防策：キャッシュ可能なコンテンツの最後のブロックに必ず cache_control を配置します

問題 #4：ツール使用のレスポンス形式エラー

エラー：invalid_request_error: tools[0].input_schema is invalid ソース：API の検証エラー 発生理由：JSON Schema が無効、必須フィールドが不足 予防策：JSON Schema バリデーターでスキーマを検証し、十分にテストします

問題 #5：ビジョンでの画像形式の問題

エラー：invalid_request_error: image source must be base64 or url ソース：API ドキュメント 発生理由：エンコードの誤り、未対応の形式 予防策：形式（JPEG/PNG/WebP/GIF）を検証し、適切な Base64 エンコードを行います

Issue #6：課金時のトークン数の不一致

エラー：予想外の高額なコスト、コンテキストウィンドウの超過 原因：トークン数のカウント方法の違い 発生理由：特殊トークンや書式設定が考慮されていない 予防策：公式のトークンカウンターを使用し、使用量ヘッダーを監視します

Issue #7：システムプロンプトの順序に関する問題

エラー：システムプロンプトが無視される、または上書きされる 原因：API の動作 発生理由：システムプロンプトが messages 配列の後に配置されている 予防策：システムプロンプトは必ず messages の前に配置します

Issue #8：コンテキストウィンドウの超過（200k）

エラー：invalid_request_error: messages: too many tokens 原因：モデルの制限 発生理由：履歴を整理せずに会話を続けている 予防策：メッセージ履歴を整理する仕組みを実装し、キャッシュを使用します

Issue #9：誤ったモデルでの拡張思考

エラー：応答に思考ブロックが含まれない 原因：モデルの機能 発生理由：提供終了または非推奨のモデル（3.5／3.7 Sonnet）を使用している 予防策：拡張思考は Claude Opus 4.5、Claude Sonnet 4.5、または Claude Opus 4 でのみ使用します

Issue #10：クライアントコードでの API キーの漏えい

エラー：CORS エラー、セキュリティ上の脆弱性 原因：セキュリティのベストプラクティス 発生理由：ブラウザーから API を呼び出している 予防策：サーバー側でのみ呼び出し、環境変数を使用します

Issue #11：レート制限のティアに関する混乱

エラー：予想より低い上限 原因：アカウントのティア制度 発生理由：ティアの引き上げの仕組みを理解していない 予防策：Console で現在のティアを確認します。使用状況に応じて自動的にスケールします

Issue #12：メッセージバッチのベータヘッダーの設定漏れ

エラー：invalid_request_error: unknown parameter: batches 原因：ベータ API の要件 発生理由：anthropic-beta ヘッダーが設定されていない 予防策：anthropic-beta: message-batches-2024-09-24 ヘッダーを含めます

Issue #13：ストリームエラーを .withResponse() で捕捉できない（v0.71.2 で修正済み）

エラー：messages.stream().withResponse() の使用時に未処理の Promise 拒否が発生する 原因：GitHub Issue #856 発生理由：SDK 内部のエラー処理により、ユーザーの catch ブロックが機能しなかった（v0.71.2 より前） 予防策：v0.71.2 以降にアップグレードするか、代わりにイベントリスナーを使用します

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);
}

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 ツールの接続による2分間のタイムアウト

エラー：約121秒後に Connection error ／ 499 Client disconnected 原因：GitHub Issue #842 発生理由：MCP ツールを実際に使用していない場合でも、MCP サーバーの接続管理が長時間実行されるリクエストと競合する 予防策：2分を超えるリクエストでは、MCP の代わりに直接 toolRunner を使用します

症状：

• MCP を使用しなければリクエストは正常に動作する
• MCP が登録されていると、約121秒で必ず失敗する
• ダッシュボードに「Client disconnected (code 499)」と表示される
• ストリーミングと非ストリーミングの両方で複数のユーザーが確認済み

回避策：

// 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
});

注：これは既知の制限であり、公式な修正はありません。ツールを使う長時間のリクエストが必要な場合は、アーキテクチャの変更を検討してください。

Issue #15：構造化出力のハルシネーションのリスク

エラー：JSON 形式は有効だが、内容が誤っている、またはハルシネーションが含まれる 原因：Structured Outputs Docs 発生理由：構造化出力が保証するのは形式への準拠であり、正確性ではありません 予防策：形式だけでなく、意味的な正しさも必ず検証します

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 行区切り文字（コミュニティからの報告）

エラー：ツールの結果に U+2028 が含まれている場合、JSON の解析に失敗する、またはエラーが通知されずに発生する 原因：GitHub Issue #882 発生理由：U+2028 は JSON では有効ですが、JavaScript の文字列リテラルでは有効ではありません 予防策：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)
};

---

公式ドキュメント

• 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

---

パッケージのバージョン

最新: @anthropic-ai/[email protected]

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

---

トークン効率:

• スキルなし: 約8,000トークン（基本設定、ストリーミング、キャッシュ、ツール、ビジョン、エラー）
• スキルあり: 約4,200トークン（知識の不足部分＋エラー防止＋重要なパターン）
• 削減量: 約48%（約3,800トークン）

防止したエラー: 解決策を明記した16件の既知の問題 主な価値: 構造化出力（v0.69.0以降）、モデルの非推奨化（2025年10月）、プロンプトキャッシュのエッジケース、ストリーミングのエラーパターン、レート制限の再試行ロジック、MCPのタイムアウト回避策、ハルシネーションの検証

---

最終確認日: 2026-01-20 | スキルのバージョン: 2.2.0 | 変更点: コミュニティ調査に基づく新たな問題を4件追加：ストリーミングのエラー処理（v0.71.2で修正）、MCPのタイムアウト回避策、構造化出力のハルシネーション検証、U+2028のサニタイズ。パフォーマンス特性と精度に関する注意事項を追加し、構造化出力のセクションを拡充。AWS Bedrockのキャッシュ制限を追加