跳到主要内容

API 参考与错误码

本页介绍 API 认证相关的错误码、API 密钥管理方式以及 HMAC 签名方案的技术规范。

API 认证错误码​

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

错误码名称HTTP说明
GA2001API_KEY_REQUIRED401请求中缺少 X-Api-Key 头。
GA2002SIGNATURE_REQUIRED401请求中缺少 X-Signature 头。
GA2011API_KEY_INVALID401API 密钥未找到或格式无效。请验证您使用的密钥是否正确。
GA2012SIGNATURE_INVALID401HMAC 签名验证失败。计算的签名与 X-Signature 不匹配。请检查规范消息构造和密钥。
GA2013TIMESTAMP_EXPIRED401请求时间戳超出 60 秒接受窗口，或 nonce 已被使用。请确保服务器时钟通过 NTP 同步。
GA2021API_KEY_DISABLED403API 密钥已被工作空间管理员禁用。请联系您的工作空间所有者。
GA2022IP_NOT_ALLOWED403客户端 IP 地址不在 API 密钥的 IP 白名单中。请在门户中添加您服务器的 IP。
GA2024SCOPE_DENIED403API 密钥没有此操作所需的权限范围。
GA2032WORKSPACE_NOT_FOUND404与此 API 密钥关联的工作空间未找到。工作空间可能已被删除。
GA2034WORKSPACE_NOT_MEMBER403与此 API 密钥关联的用户不是目标工作空间的成员。
提示 调试认证失败

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

API 密钥管理​

API 密钥通过 Lampay 控制台由工作空间所有者管理。您可以在工作空间设置页面创建、查看、吊销和重新生成密钥。

API 密钥格式​

API 密钥采用前缀格式来标识环境：

前缀环境示例
sk_live_生产环境sk_live_abc123def456ghi789
sk_test_沙箱 / 测试环境sk_test_xyz987wvu654tsr321
注意 密钥对可见性

API 密钥对仅在创建或重新生成时显示一次。如果您丢失了密钥对，必须重新生成。无法检索之前签发的密钥对。

密钥生命周期​

  已创建（活跃）
       │
       ├── 重新生成密钥对 → 新密钥对，密钥 ID 不变
       │
       └── 吊销 → 永久禁用（GA2021）

配置选项​

创建或更新 API 密钥时，可以配置以下内容：

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

技术规范​

参数值
签名算法HMAC-SHA256
请求体哈希算法SHA-256（十六进制编码，小写）
签名编码Base64（标准，含填充）
时间戳格式Unix epoch 秒数（UTC）
时间戳容差60 秒（如 |当前时间 - 时间戳| > 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 Secret 是 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 网关后面，请使用 Lampay 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、移动应用或客户端配置中。

相关页面​