n8n API 集成模式
该技能面向 n8n v1.x，说明 HTTP Request 节点的配置、认证、分页、响应处理和批量请求用法。
快速参考
任务与做法：
- 调用 REST API：HTTP Request 节点，配置方法、URL 和认证。
- 用 API 密钥认证：预定义凭证或通用凭证（Header Auth / Query Auth）。
- 用 OAuth2 认证：预定义 OAuth2 凭证并配置回调 URL。
- 处理分页响应：使用 HTTP Request 节点的分页选项（offset、cursor 或基于链接）。
- 下载文件：将 Response Format 设为 File。
- 发送 JSON 请求体：Body Content Type = JSON，提供键值对或原始 JSON。
- 发送表单数据：Body Content Type = Form-Data（multipart 或 URL 编码）。
- 批量调用：在 HTTP Request 节点前加 Split In Batches 节点。
- 处理 API 错误：按节点启用 Retry On Fail 和/或 Continue On Fail。
- 读取响应元数据：$response.statusCode、$response.headers、$response.body。
认证方式决策
需要调用外部 API 时：
- API 有内置 n8n 节点：使用专用节点及其预定义凭证。
- 使用 API 密钥：密钥在请求头则用通用凭证（Header Auth）；密钥在查询字符串则用通用凭证（Query Auth）；密钥在请求体则用 HTTP Request 节点配合表达式。
- 使用 OAuth2：n8n 有预定义 OAuth2 凭证则优先使用；没有则用通用 OAuth2 API 凭证。
- 使用 Basic Auth：用通用凭证（Basic Auth）或 HTTP Request Header Auth 凭证。
- 使用 Bearer Token：用通用凭证（Header Auth），值为 Authorization: Bearer <token>。
分页策略决策
API 返回分页结果时：
- 响应包含下一页 URL：使用 Response Contains Next URL 模式。
- 响应包含 cursor/token：使用 Response Contains Next URL 并映射 cursor 参数。
- 使用 offset + limit：使用 Specify How Each Page Is Determined 并递增 offset。
- 使用页码：使用 Specify How Each Page Is Determined 并递增页码。
HTTP Request 节点配置
方法：GET 取数据（不要带请求体）；POST 创建资源或发送数据；PUT 全量替换；PATCH 部分更新；DELETE 删除；HEAD 检查资源是否存在且不返回正文。
URL：始终使用带协议的完整 URL，如 https://api.example.com/v1/resource；动态 URL 用表达式，如 https://api.example.com/v1/users/{{ $json.userId }}；不要在 URL 中硬编码凭证。
请求体类型：JSON 用于多数 REST API；Form URL-Encoded 用于 application/x-www-form-urlencoded；Form-Data (Multipart) 用于文件上传或混合数据；Binary 用于原始二进制；Raw 用于 XML、纯文本、GraphQL 等自定义类型；n8n Binary File 用于发送上游节点的二进制文件。
请求头与查询参数：在 Headers 和 Query Parameters 区域以键值对添加，值可用表达式；使用 Raw 请求体时始终显式设置 Content-Type。
响应处理：Response Format 可选 JSON（解析为 $json）、Text（原始文本在 $json.data）、File（二进制附件）和 Autodetect（按 Content-Type 判断）。响应元数据仅在 HTTP Request 节点上下文可用：$response.statusCode、$response.headers、$response.body、$response.statusMessage。
认证选项
预定义凭证：有则优先使用，n8n 内置 400+ 服务的凭证。在 HTTP Request 节点设置 Authentication 为 Predefined Credential Type，选择服务并创建或选择凭证。
通用凭证：无预定义凭证时使用。Header Auth 注入自定义请求头；Query Auth 注入 URL 查询参数；Basic Auth 使用 Authorization: Basic 头；Digest Auth 使用 HTTP Digest；OAuth1 API 走 OAuth 1.0a；OAuth2 API 走 OAuth 2.0（授权码、客户端凭证）；Custom Auth 可自定义请求头、查询参数或请求体字段。
OAuth2 配置：新建 OAuth2 API 凭证，填写 Authorization URL、Access Token URL、Client ID、Client Secret、Scope（空格分隔）及需要的 Auth URI Query Parameters；复制 n8n 凭证表单中显示的 OAuth 回调 URL，并在服务商开发者控制台注册；点击 Connect my account 完成授权。提供 Refresh Token 时 n8n 会自动刷新令牌，不要在工作流逻辑中手动保存令牌。回调 URL 格式：https://<n8n-host>/rest/oauth2-credential/callback。
分页
在 HTTP Request 节点 Options > Pagination 中启用。模式一：Response Contains Next URL，从响应中提取下一页 URL，例如 {{ $response.body.next }} 或 {{ $response.headers.link }}，并设置最大页数上限防止死循环。模式二：Specify How Each Page Is Determined，为 offset、cursor 或页码 API 手动配置页大小和分页参数递增逻辑，可用 $pageCount 读取当前页数。始终配置停止条件：Maximum Pages 硬上限，或 Complete When 表达式（如 {{ $response.body.results.length === 0 }}、{{ $response.body.hasMore === false }}）。
批量请求
向有速率限制或需要批量操作的 API 发送大量条目时：在 HTTP Request 前加 Split In Batches 节点，批量大小与 API 速率限制匹配；将 HTTP Request 连接到其输出；如有限速延迟需求，在 HTTP Request 后加 Wait 节点并循环回 Split In Batches。HTTP Request 默认逐条处理输入，50 条会发起 50 次调用；有速率限制时必须分批，避免 429 错误。
API 调用错误处理
Retry On Fail：在节点 Settings 中启用，Max Tries 建议 3 次，Wait Between Tries 建议 1000ms（限流 API 可增大）。外部 API 调用建议始终启用，以应对网络问题和限流造成的瞬时失败。
Continue On Fail：启用后 API 出错不会导致工作流失败，失败条目的 $json.error 含错误详情，可在后续用 IF 节点分流错误与成功。
错误输出分支：HTTP Request 支持第二个错误输出连接器，可将失败请求路由到单独处理路径，检查 $json.error、$json.statusCode。
状态码处理：在 HTTP Request 后用 IF 节点按 $response.statusCode 分支，如 200 成功、429 限流需重试或等待、>=400 客户端或服务端错误。
通用凭证请求模式
对没有专用 n8n 节点的自定义 API：创建通用凭证（Header Auth、Query Auth 或 OAuth2）并配置认证信息；在 HTTP Request 节点中选择 Authentication > Predefined Credential Type，选择所建通用凭证类型；用 URL、方法、请求头、查询参数和请求体构建请求。凭证会加密保存并可跨多个 HTTP Request 节点复用。
关键规则
始终优先用预定义凭证而非手动注入请求头；始终设置分页上限防止无限请求；始终为外部 API 调用启用 Retry On Fail；有速率限制的批量操作始终用 Split In Batches。绝不在表达式或 URL 中硬编码 API 密钥、令牌或机密；绝不用 Code 节点发 HTTP 请求，始终用 HTTP Request 节点；GET 或 HEAD 方法绝不发送请求体；绝不忽略 $response.statusCode，始终处理非 200 响应。
参考文件
methods.md：HTTP Request 节点选项、OAuth2 流程、分页选项、通用凭证。 examples.md：REST API 集成、OAuth2 流程、分页抓取、批量请求。 anti-patterns.md：常见集成错误与修正。