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：签名无效
这是最常见的错误。请按以下清单逐步排查：
- 请求体哈希不匹配。 打印您正在哈希的精确字节字符串，并与 HTTP 库实际发送的精确字节字符串进行比较。注意空白、键顺序或字符编码的差异。
- 路径错误。 规范消息仅使用请求路径——不包含协议（
https://）、主机或查询字符串。对于/api/v1/wallets?page=0，应使用/api/v1/wallets。 - 换行符问题。 确保使用
\n（LF，0x0A）作为分隔符。某些平台默认使用\r\n（CRLF），这会产生不同的哈希值。 - 密钥编码。 API 密钥是 UTF-8 字符串。不要在将其用作 HMAC 密钥之前对其进行 Base64 解码——直接使用原始字符串。
- Base64 输出。 签名必须是标准 Base64（使用
+、/和=填充）。不要使用 Base64-URL 编码。
GA2013：时间戳过期
- 时钟偏移。 在您的服务器上运行
date -u +%s并与已知的 NTP 源进行比较。如果差异超过 60 秒，请同步您的时钟。 - Nonce 重复使用。 相同的错误码也用于重复的 nonce。如果您的时钟正确，请确保为每个请求生成新的 UUID。
- 缓存的时间戳。 如果您计算一次时间戳并在多个请求中重复使用（例如在批量循环中），批次末尾的请求可能超过 60 秒的窗口。
GA2021：API 密钥已禁用
管理员已通过门户禁用了此密钥。请联系您的工作区所有者。一旦禁用，密钥无法重新启用——您必须创建新的密钥。
GA2022：IP 不被允许
您服务器的出站 IP 与此 API 密钥配置的白名单不匹配。如果您的服务器位于负载均衡器或 NAT 网关之后，请使用 SlaunchX API 可见的外部 IP。您可以使用 curl ifconfig.me 进行检查。
安全最佳实践
安全存储密钥。 使用密钥管理器（如 HashiCorp Vault、AWS Secrets Manager 等），而非将环境变量或配置文件提交到版本控制中。
定期轮换密钥。 使用重新生成端点来颁发新密钥。协调轮换过程，确保在旧密钥失效之前更新您的服务器。
使用 IP 白名单。 将 API 密钥的使用限制在已知的服务器 IP 地址。即使密钥泄露，也能防止被滥用。
应用最小权限范围。 仅授予每个密钥实际需要的权限范围。为不同的服务或使用场景创建不同的密钥。
同步您的时钟。 使用 NTP 将服务器时钟保持在 UTC 几秒钟之内。60 秒的时间戳窗口已经很宽裕，但超出此范围的时钟偏移会导致持续出现
GA2013错误。切勿在客户端暴露密钥。 API 密钥只能在服务端代码中使用。切勿将其嵌入前端 JavaScript、移动应用或客户端配置中。