Anthropic API/Anthropic Messages 响应、流式与错误处理

解析 Anthropic Messages 响应结构、审计头、SSE 流式事件与标准错误处理。

Anthropic Messages 响应、流式与错误处理

本文档详细说明通过 UniGateway 调用 Anthropic Messages API(POST /v1/messages)时的完整响应体格式、审计响应头、Server-Sent Events (SSE) 流式传输规范及标准错误处理策略。


章节导引

本篇为 Anthropic Messages API 参考的第 6 章节:

  1. Messages 概述与快速开始
  2. 请求参数与消息格式
  3. 扩展推理 Thinking
  4. 提示词缓存 Prompt Caching
  5. 工具调用与 Computer Use
  6. 响应、流式与错误处理(当前章节)

核心响应体结构

当以非流式(默认 stream: false)发起请求并成功完成后,API 返回如下格式的 JSON 对象:

{
  "id": "msg_01X9DhjKLmnoPQRsTUvwxYZ1",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "分布式一致性协议 Raft 主要通过 Leader 选举与日志复制来确保多节点状态的一致..."
    }
  ],
  "model": "claude-sonnet-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 28,
    "output_tokens": 156,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

字段说明

字段名类型说明
idstring本次生成的唯一消息标识符(以 msg_ 为前缀)
typestring固定为 "message"
rolestring固定为 "assistant"
contentarray输出内容块数组,包含 text、thinking、redacted_thinking 或 tool_use 块
modelstring实际处理请求的模型名称(保持与客户端请求名称一致)
stop_reasonstring模型停止生成的原因:<br>• "end_turn":自然生成结束<br>• "max_tokens":达到 max_tokens 限制<br>• "stop_sequence":命中停止序列<br>• "tool_use":模型请求执行工具
stop_sequencestring | null触发终止的停止序列字符串(未触发时为 null)
usageobject本次调用的 Token 消耗明细,包含常规输入/输出与缓存读写指标

协议适配与可观测响应头

当 UniGateway 执行跨平台或跨代际出站协议规范化与请求自适应调整时,通过标准 HTTP 响应头向客户端反馈实际生效的处理:

响应头格式与示例触发场景说明
x-gateway-modifiedthinking.type=enabled=>adaptive,temperature=1.0=>@absent列出本次请求对客户端可见的字段级修改(格式:path=from=>to;移除记为 @absent,脱敏值记为 @redacted,复杂结构记为 @details)
x-gateway-modified-count2本次请求实际生效的规范化修改总项数
x-gateway-modified-statefinal / pending / not_committed审计头定稿状态(final 表示改写已全部定稿)
x-gateway-modified-truncatedtrue当 x-gateway-modified 长度超过 1024 字节上限发生截断时输出
x-gateway-degradedthinking_disabled_for_forced_tool当触发有损兼容降级时标识对应的规则摘要
x-gateway-rectifiedthinking_enabled_to_adaptive命中的主动迁移或自适应重试修复规则标签
X-Gateway-Error-Classinference_capability_unavailable非 200 错误响应的标准化错误分类标识(如 invalid_request_error、inference_capability_unavailable、inference_undetermined_rejection、inference_model_unavailable、inference_service_error)
X-Gateway-Retryabletrue / false指示当前错误响应是否建议重试(可重试时同步返回 Retry-After 头)

客户端直通控制头

若开发者正在进行严格的客户端 SDK 规范合规性测试,希望完全关闭网关的参数适配与自动重试,可在请求头中携带:

x-gateway-rectify-opt-out: true

网关将对该请求采用完全直通转发,不执行任何字段修剪或自适应重试,直接返回上游原生响应。


Server-Sent Events (SSE) 流式传输

当在请求体中设置 "stream": true 时,API 将以 text/event-stream 格式实时推送事件。

流式事件生命周期管道

  1. event: message_start:流式建立,推送初始消息元数据(包含消息 ID、模型及初始 usage.input_tokens);
  2. event: content_block_start:新内容块开始(指示当前块的 index 及 type,如 text、thinking 或 tool_use);
  3. event: content_block_delta:内容增量块。对于文本块推送 text_delta;对于思考块推送 thinking_delta 或 signature_delta;对于工具调用推送 input_json_delta;
  4. event: content_block_stop:当前内容块完成;
  5. event: message_delta:消息完成增量,携带最终的 stop_reason、stop_sequence 及 usage.output_tokens;
  6. event: message_stop:整个流正常终止。

流式输出代码示例

Python SDK

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ.get("UNIGATEWAY_API_KEY"),
    base_url="https://api.unigateway.ai",
)

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "用三句话解释量子纠缠。"}],
) as stream:
    for event in stream:
        if event.type == "text":
            print(event.text, end="", flush=True)
        elif event.type == "thinking":
            print(f"\n[思考中]: {event.thinking}", end="", flush=True)

print()

TypeScript SDK

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

const client = new Anthropic({
  apiKey: process.env.UNIGATEWAY_API_KEY,
  baseURL: 'https://api.unigateway.ai',
});

const stream = await client.messages.create({
  model: 'claude-sonnet-5-5',
  max_tokens: 2048,
  thinking: { type: 'adaptive' },
  output_config: { effort: 'medium' },
  messages: [{ role: 'user', content: '用三句话解释量子纠缠。' }],
  stream: true,
});

for await (const messageStreamEvent of stream) {
  if (messageStreamEvent.type === 'content_block_delta') {
    const delta = messageStreamEvent.delta as any;
    if (delta.type === 'text_delta') {
      process.stdout.write(delta.text);
    } else if (delta.type === 'thinking_delta') {
      process.stdout.write(`[Thinking]: ${delta.thinking}`);
    }
  }
}
console.log();

错误处理规范

标准错误响应格式

所有非 200 响应均严格对齐 Anthropic 官方错误 JSON 规范:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: integer below minimum value. Expected >= 1, got 0."
  }
}

常见状态码与网关行为

状态码错误类型 (error.type)触发原因与网关处理策略
400 Bad Requestinvalid_request_error入口参数语法损坏、违反目标模型契约或后端返回明确的参数校验错误。若后端仅返回无参数定位的笼统拒绝,网关自动切换候选通道并在耗尽后转为 502(inference_undetermined_rejection)。
401 Unauthorizedauthentication_errorAPI Key 缺失、格式无效或已被系统禁用。
403 Forbiddenforbidden_errorAPI Key 无权访问目标模型,或所属分组设置了特定客户端白名单。
404 Not Foundnot_found_error请求的模型未在网关发布或当前分组无对应路由(已发布模型在候选推理通道均暂不可用时返回 502 inference_model_unavailable)。
413 Payload Too Largerequest_too_large请求体超过允许的最大字节数(全局上限 128MB,或超出当前分组内所有可用通道的平台上限)。
429 Too Many Requestsrate_limit_error触发客户端 API Key 限流;若为单一推理通道限流,网关调度器会自动切换至其他健康通道重试。
502 Bad Gateway / 503api_error(inference_*)统一使用 inference_* 错误码标识推理服务与容量状态:inference_capability_unavailable(请求符合规范但当前无支持该特性的推理容量,附带 unmet_capabilities)、inference_undetermined_rejection(无明确参数诊断的后端拒绝)、inference_model_unavailable(已发布模型暂不可用)、inference_service_error / inference_capacity_exhausted(502)及 inference_overloaded(503)。可重试错误附带 X-Gateway-Retryable: true 与 Retry-After。

受信云平台信封拆解与品牌脱敏

为保证多云通道下一致的标准 API 行为,网关在错误返回路径上应用严格的清洗与解包规范:

  • 受信云厂商校验信封拆解(Trusted Cloud Provider Envelope Unwrapping):当底层通道(如 AWS Bedrock 或 Google Cloud Vertex AI)返回包裹在 SDK 或云厂商信封内的参数错误时(例如 AWS Bedrock 的 InvokeModelWithResponseStream: operation error Bedrock Runtime: ... ValidationException: ...,或 Vertex AI 的 {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}),网关自动拆解外层信封,提取内层原始诊断语义进行规范化匹配:
    • 自动剥离传输层标记与请求追踪 ID(如 AWS SDK 的 RequestID: <uuid>、(request id: ...)、rid=HEX 等),防止底层云厂商元数据干扰客户端排错;
    • 经解包校验的真实参数错误,保留干净的标准错误消息返回客户端,格式严格对齐原生 Anthropic API。
  • 第三方中继身份脱敏(Third-Party Relay Identity Scrubbing):若上游通道返回的错误消息中包含第三方中继或代理平台的品牌标识与错误代号(如 openrouter、vercel、fireworks、together ai、poe 等),网关执行两级脱敏:内部错误代号就地替换,包含品牌话术的整段错误直接掩码为标准的网关错误格式,确保客户端获得中立统一的原生体验。

anthropic-beta 请求头跨多云载体转换

Anthropic 官方通过 anthropic-beta 头控制特性开关。在多云架构中,不同渠道对 Beta 头的承载机制各异:

特性项Direct API 格式AWS Bedrock 格式Google Cloud Vertex AI 格式
Prompt Cachingprompt-caching-2024-07-31原生支持,自动透传通过 Query 参数或请求体扩展字段注入
Computer Usecomputer-use-2024-10-22 或 computer-use-2025-01-24自动映射为 Bedrock 专有 Header映射为 Vertex 对应端点参数
上下文编辑与压缩context-management-2025-06-27 / compact-2026-01-12按目标通道支持能力封装至请求体 anthropic_beta按目标通道支持能力封装至请求体 anthropic_beta

网关自动识别客户端传入的 anthropic-beta 并根据实际转发的目标云平台进行适配,开发者无需针对各云服务商单独维护多套代码。


下一步