文档认证方式
认证方式
API Key 认证与限流规则说明
API Key 认证
所有数据接口通过 X-API-Key HTTP Header 进行认证。
curl -H "X-API-Key: sk_gapi_你的密钥" \
"https://api.groundapi.net/v1/finance/stock?symbol=600519"获取 API Key
- 登录 GroundAPI 控制台
- 点击「创建新 Key」
- 输入 Key 名称（如 "生产环境"）
- 复制并保存密钥，密钥只在创建时展示一次
Key 格式
API Key 格式为 sk_gapi_ + 32 位随机字符，例如：
sk_gapi_a3b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2服务端存储的是 SHA256 哈希值，即使数据库泄露也无法还原原始 Key。
限流规则
采用 Redis 滑动窗口算法，按用户维度限流：
| 用户类型 | 频率限制 |
|---|---|
| 免费用户 | 60 次/分钟 |
| 付费用户 | 300 次/分钟 |
超限时返回 429 Too Many Requests：
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "请求频率超限，请稍后重试",
"docs": "https://docs.groundapi.net/errors#rate_limit_exceeded"
}
}响应头包含 Retry-After 字段，单位秒。
错误码一览
| HTTP 状态码 | 错误码 | 说明 |
|---|---|---|
| 401 | INVALID_API_KEY | API Key 缺失、无效或已禁用 |
| 429 | RATE_LIMIT_EXCEEDED | 请求频率超限 |
| 400 | INVALID_PARAMS | 请求参数缺失或格式错误 |
| 502 | UPSTREAM_ERROR | 上游数据源异常 |
| 503 | SERVICE_UNAVAILABLE | 服务暂时不可用 |
19 天前更新