鉴权
如何携带 API Key、管理 Key，以及如何读取限流响应头。
所有 /v1 接口都需要 API Key。Key 在控制台 /dashboard/keys 创建和管理。
携带 Key
以下两种请求头任选其一，效果相同。
| 请求头 | 示例 |
|---|---|
X-API-Key（推荐） | X-API-Key: shapi_xxxxxxxx |
Authorization | Authorization: Bearer shapi_xxxxxxxx |
curl https://api.serphubapi.com/v1/account \
-H "Authorization: Bearer shapi_xxxxxxxx"
不要把 Key 放进 URL 查询参数、前端代码或公开代码仓库。请从你自己的服务端，或你能控制的 agent 运行环境中调用 SerpHubAPI。
Key 格式
- 新发放的 Key 以
shapi_开头。 - 早期以
fapi_开头的 Key 继续有效，用法完全一样，无需更换。 - Key 只在创建时显示一次。我们只存储哈希值，不存原文。丢失后请新建一个，并停用旧 Key。
管理 Key
在 /dashboard/keys 可以：
- 创建多个 Key 并命名，例如按环境或按客户项目分开。
- 停用、重新启用或删除 Key。停用后立即失效。
- 为每个 Key 设置每日积分上限。该 Key 在当天（UTC）消耗的积分达到上限后，后续调用返回
429 rate_limited，提示daily credit limit for this API key reached，次日自动恢复。同账户的其他 Key 不受影响。 - 为每个 Key 设置 IP 白名单（单个 IP 或 CIDR 网段）。来自其他地址的请求会被拒绝，返回
401 invalid_api_key。留空表示不限制。
同一账户下的所有 Key 共用一个积分余额。
限流
限流按 Key、按分钟计算。每个成功响应都带有以下响应头：
| 响应头 | 含义 |
|---|---|
X-RateLimit-Limit | 该 Key 每分钟允许的请求数 |
X-RateLimit-Remaining | 当前窗口剩余可用请求数 |
X-RateLimit-Reset | 距窗口重置的秒数 |
超出限制时返回 429，错误码 rate_limited，并附带 Retry-After 响应头（秒）。等待相应时间后重试即可。如需更高限额，请发邮件至 support@serphubapi.com。
鉴权错误
所有鉴权失败均返回 401，错误码 invalid_api_key，具体原因见 message：
| message | 原因 |
|---|---|
missing or invalid API key | 未携带 Key，或 Key 不存在 |
API key is disabled | 该 Key 已在控制台停用 |
account is suspended | 账户已被暂停，请联系客服 |
request IP is not in this API key's allowlist | 请求来源 IP 不在该 Key 的白名单内 |
完整错误码见错误码。