请求与响应格式常见问题

编辑部发布 2026-06-26 更新 2026-06-27 10 分钟阅读 1,853 字

请求与响应格式是 API 交互时传输数据的具体结构和规范。对于 Claude API 用户而言，最核心的是新版 Messages API 采用的 JSON 格式，它已取代旧版 Text Completions API。掌握这一格式不仅直接决定请求能否成功，更深远地影响着 Token 计费精度、错误定位效率以及多轮对话的流程管控。本文梳理了实际使用中的高频问题，为你提供一套可即查即用的操作与排障指南。

开始前须知

在构造请求前，请先确认基础环境已达到以下要求：

API Key 有效且未过期：前往 Anthropic Console 验证 Key 状态。注意切勿将 Key 硬编码在公开代码中。
API 版本标头正确：建议始终在请求头中添加 anthropic-version: 2023-06-01 或更新的稳定版本号，以免因默认版本变更引发行为偏差。
了解当前支持的模型：不同模型（如 claude-3-5-sonnet-20241022、claude-3-haiku-20240307）对 max_tokens、system 等参数有不同上限。请查阅官方模型文档确认。
测试工具就绪：建议先在 Postman、curl 或官方 Workbench 中验证单个请求，再集成到代码。

核心操作步骤

1. 构造正确的请求体

Messages API 请求体是一个 JSON 对象，包含以下必填字段：

字段	类型	说明	常见错误
`model`	string	模型名称，如 `claude-3-5-sonnet-20241022`	拼写错误或使用已弃用的模型别名
`max_tokens`	integer	生成的最大 Token 数，不能超过模型限制	忘记设置导致默认值过低或过高被拒绝
`messages`	array	对话历史，格式为 `[{"role": "user" or "assistant", "content": "文本"}]`	角色顺序错误或 content 为空字符串

一个完整的基础请求示例：

{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "用一句话解释什么是 API"}
  ]
}

请求头需要添加：

Content-Type: application/json
x-api-key: <你的API Key>
anthropic-version: 2023-06-01

边界情况：构建多轮对话时，messages 数组必须严格交替 user 和 assistant 角色，不能出现连续两个相同角色，也不能以 assistant 开头。若从数据库读取的历史对话存在缺失，需先进行数据清洗补全。

2. 解析响应结构

成功响应的结构如下：

{
  "id": "msg_01ABC...",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "API 是应用程序之间通信的桥梁。"
    }
  ],
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 18,
    "output_tokens": 16
  }
}

几个容易忽略的字段：

stop_reason：end_turn 表示模型自然结束；max_tokens 表示达到设定的 Token 上限；stop_sequence 表示触发了自定义停止序列。频繁出现 max_tokens 时，说明回答被截断，需增大 max_tokens 或优化提示词。
usage：包含输入和输出 Token 数，计费以此为准。注意 System 提示和工具消耗的 Token 也会计入 input_tokens。

3. 处理流式与非流式响应

非流式（默认）：API 返回完整响应 JSON。适用于简短回答或无需实时显示的场景。
流式（Streaming）：在请求中添加 "stream": true，API 以 Server-Sent Events（SSE）格式逐块推送 content_block_delta 事件。响应不再是完整 JSON，需逐行解析 data: 开头的数据行，直到收到 event: message_stop。

流式响应常见问题：

早期实现者错误地等待 message_stop 后才更新 UI，失去了流式应有的逐字显示效果。
网络中断时仅收到部分数据，建议在客户端实现断点续传或重试逻辑。

检查清单

model 名称拼写无误，且与你账户可用的模型一致。
messages 数组首条角色为 user，且角色严格交替。
content 字段不为空字符串或空数组。
max_tokens 在模型允许范围内（如 claude-3-5-sonnet-20241022 最大 8192）。
请求头中包含 Content-Type、x-api-key 和 anthropic-version。
若使用流式，确认客户端能正确解析 SSE 行格式，而非等待完整 JSON 响应。
解析响应时检查 stop_reason 是否为 max_tokens，若是则考虑增大上限。

故障排查指南

新手最容易卡在以下几个环节，请按顺序自查：

问题：HTTP 400 Bad Request

原因通常是 messages 格式不正确。检查角色顺序、content 是否为空、是否存在未知字段。
简单调试方法：将 JSON 复制到在线校验器（如 jsonlint.com）先验证语法。

问题：HTTP 401 Unauthorized

确认 API Key 未过期且无多余空格。若 Key 在环境变量中，确认变量名匹配且已正确加载。
检查请求头名称：应为 x-api-key，而非 Authorization（除非使用代理网关）。

问题：HTTP 429 Too Many Requests

速率限制触发。查看响应头中的 anthropic-ratelimit 系列字段，了解当前限制和重置时间。
短期方案：加入指数退避重试机制。长期方案：联系官方提升限额，或分散请求到多个 Key。

问题：响应内容异常或截断

检查 stop_reason。若为 max_tokens，增大 max_tokens，并考虑在提示词中加入“请详细回答”等引导。
若 stop_reason 为 stop_sequence，确认并非自定义停止序列意外触发。若将空字符串设为停止序列，部分 API 版本会立即停止。

何时应暂停操作：连续收到 500 或 503 服务端错误时，等待 30 秒后重试。若错误持续超过 10 分钟，检查 Anthropic 状态页面是否有已公告的故障。

常见疑问解答