API 参考与错误码

本页涵盖 API 认证相关的错误码、API 密钥管理方法以及 HMAC 签名方案的技术规格。

API 认证错误码

当服务器在 验证流水线 中拒绝 API 请求时，会返回以下错误码之一。流水线按顺序评估——第一个失败的检查决定了错误响应。

错误码	名称	HTTP	说明
GA2001	API_KEY_REQUIRED	401	请求中缺少 X-Api-Key 请求头。
GA2002	SIGNATURE_REQUIRED	401	请求中缺少 X-Signature 请求头。
GA2011	API_KEY_INVALID	401	未找到 API 密钥或格式无效。请确认您使用的是正确的密钥。
GA2012	SIGNATURE_INVALID	401	HMAC 签名验证失败。计算的签名与 X-Signature 不匹配。请检查您的规范消息构造和密钥。
GA2013	TIMESTAMP_EXPIRED	401	请求时间戳超出 60 秒的可接受窗口，或 nonce 已被使用。请确保您的服务器时钟已通过 NTP 同步。
GA2021	API_KEY_DISABLED	403	API 密钥已被工作区管理员禁用。请联系您的工作区所有者。
GA2022	IP_NOT_ALLOWED	403	客户端 IP 地址不在 API 密钥的 IP 白名单中。请在管理门户中添加您服务器的 IP。
GA2024	SCOPE_DENIED	403	API 密钥没有此操作所需的权限范围。
GA2032	WORKSPACE_NOT_FOUND	404	未找到与此 API 密钥关联的工作区。该工作区可能已被删除。
GA2034	WORKSPACE_NOT_MEMBER	403	与此 API 密钥关联的用户不是目标工作区的成员。

调试认证失败

首先检查 HTTP 状态码和响应体中的 code 字段。按照 验证流水线 的顺序逐步排查：如果您看到 GA2013，请先修复时间戳或 nonce，再排查签名问题。GA2012 最常见的原因是哈希计算和实际请求体之间的 JSON 序列化不一致。

---

API 密钥管理

API 密钥由工作区所有者通过 SlaunchX 管理面板进行管理。您可以在工作区设置页面中创建、查看、撤销和重新生成密钥。

API 密钥格式

API 密钥采用带前缀的格式，用于标识环境：

前缀	环境	示例
sk_live_	生产环境	sk_live_abc123def456ghi789
sk_test_	沙箱 / 测试环境	sk_test_xyz987wvu654tsr321

:::caution 密钥可见性 API 密钥仅在创建或重新生成时 显示一次。如果您丢失了密钥，必须重新生成。没有办法检索以前颁发的密钥。 :::

密钥生命周期

  已创建（活跃）
       │
       ├── 重新生成密钥 → 新密钥，相同密钥 ID
       │
       └── 撤销 → 永久禁用（GA2021）

配置选项

创建或更新 API 密钥时，您可以配置：

• 权限范围 -- 限制密钥可以执行的 API 操作。如果请求需要密钥不具备的权限范围，服务器将返回 GA2024。
• IP 白名单 -- 限制可以使用该密钥的 IP 地址。来自未列入名单的 IP 的请求将收到 GA2022。留空则允许所有 IP。
• 描述 -- 用于帮助您识别密钥用途的可读标签。

---

技术规格

参数	值
签名算法	HMAC-SHA256
请求体哈希算法	SHA-256（十六进制编码，小写）
签名编码	Base64（标准格式，带填充）
时间戳格式	Unix 时间戳（秒，UTC）
时间戳容差	60 秒（服务器在 `
Nonce 格式	任意唯一字符串；建议使用 UUID v4
Nonce 唯一性强制执行	服务端；在时间戳窗口内唯一
空请求体哈希	e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
规范消息格式	method\npath\ntimestamp\nnonce\nbodyHash
规范消息中的路径	仅请求路径（不含协议、主机或查询字符串）

速率限制

API 端点可能根据操作类型实施速率限制。当超过速率限制时，服务器返回 HTTP 429 Too Many Requests。响应中包含 Retry-After 请求头，指示在重试前需要等待的秒数。

请求大小限制

限制	值
最大请求体大小	1 MB
最大 URL 长度	8,192 字符

---

故障排除指南

以下是集成人员最常遇到的问题及诊断步骤。

GA2012：签名无效

这是最常见的错误。请按以下清单逐步排查：

1. 请求体哈希不匹配。 打印您正在哈希的精确字节字符串，并与 HTTP 库实际发送的精确字节字符串进行比较。注意空白、键顺序或字符编码的差异。
2. 路径错误。 规范消息仅使用请求路径——不包含协议（https://）、主机或查询字符串。对于 /api/v1/wallets?page=0，应使用 /api/v1/wallets。
3. 换行符问题。 确保使用 \n（LF，0x0A）作为分隔符。某些平台默认使用 \r\n（CRLF），这会产生不同的哈希值。
4. 密钥编码。 API 密钥是 UTF-8 字符串。不要在将其用作 HMAC 密钥之前对其进行 Base64 解码——直接使用原始字符串。
5. Base64 输出。 签名必须是标准 Base64（使用 +、/ 和 = 填充）。不要使用 Base64-URL 编码。

GA2013：时间戳过期

1. 时钟偏移。 在您的服务器上运行 date -u +%s 并与已知的 NTP 源进行比较。如果差异超过 60 秒，请同步您的时钟。
2. Nonce 重复使用。 相同的错误码也用于重复的 nonce。如果您的时钟正确，请确保为每个请求生成新的 UUID。
3. 缓存的时间戳。 如果您计算一次时间戳并在多个请求中重复使用（例如在批量循环中），批次末尾的请求可能超过 60 秒的窗口。

GA2021：API 密钥已禁用

管理员已通过门户禁用了此密钥。请联系您的工作区所有者。一旦禁用，密钥无法重新启用——您必须创建新的密钥。

GA2022：IP 不被允许

您服务器的出站 IP 与此 API 密钥配置的白名单不匹配。如果您的服务器位于负载均衡器或 NAT 网关之后，请使用 SlaunchX API 可见的外部 IP。您可以使用 curl ifconfig.me 进行检查。

---

安全最佳实践

1. 安全存储密钥。 使用密钥管理器（如 HashiCorp Vault、AWS Secrets Manager 等），而非将环境变量或配置文件提交到版本控制中。

2. 定期轮换密钥。 使用重新生成端点来颁发新密钥。协调轮换过程，确保在旧密钥失效之前更新您的服务器。

3. 使用 IP 白名单。 将 API 密钥的使用限制在已知的服务器 IP 地址。即使密钥泄露，也能防止被滥用。

4. 应用最小权限范围。 仅授予每个密钥实际需要的权限范围。为不同的服务或使用场景创建不同的密钥。

5. 同步您的时钟。 使用 NTP 将服务器时钟保持在 UTC 几秒钟之内。60 秒的时间戳窗口已经很宽裕，但超出此范围的时钟偏移会导致持续出现 GA2013 错误。

6. 切勿在客户端暴露密钥。 API 密钥只能在服务端代码中使用。切勿将其嵌入前端 JavaScript、移动应用或客户端配置中。

---

相关页面

• HMAC 认证 -- 带有代码示例的分步签名计算。
• API 集成概述 -- 何时使用 API 集成与 Web 集成。
• 错误处理 -- 所有领域的完整错误码目录。