限速规则
为了保护 API 服务的稳定性和公平性，我们对公开 API 实施了基于 IP 的限速机制。
默认限额
每个 IP 地址默认享有以下限额：
- Name
每日请求次数- Description
150 次
- Name
重置时间- Description
每天 UTC 0:00（北京时间早上 8:00）
- Name
计费单位- Description
按 IP 地址计算
限额计算规则
- 每次 API 调用消耗 1 次请求配额
- 无论请求成功或失败（除网络错误外），都会计入配额
- 404（未找到）、400（参数错误）等响应也会消耗配额
- 只有 429（超限）响应不消耗配额
Rate Limit 信息
{
"rateLimit": {
"remaining": 148,
"limit": 150,
"reset": "2025-10-24T00:00:00.000Z"
}
}
响应中的 rateLimit 字段显示了当前的配额使用情况。
响应头
每个 API 响应都包含以下响应头，方便您监控配额使用：
- Name
X-RateLimit-Limit- Description
每日总限额（通常为 150）
- Name
X-RateLimit-Remaining- Description
今日剩余请求次数
- Name
X-RateLimit-Reset- Description
配额重置时间（ISO 8601 格式）
查看响应头
curl -I "https://api.keykey.cc/api/public/memory-card?word=hello"
# 响应头示例
# X-RateLimit-Limit: 150
# X-RateLimit-Remaining: 148
# X-RateLimit-Reset: 2025-10-24T00:00:00.000Z
超限处理
当您的请求次数超过每日限额时，API 会返回 429 Too Many Requests 状态码。
超限响应
- 状态码: 429
- 错误码:
RATE_LIMIT_EXCEEDED - 建议: 等待配额重置或联系管理员申请白名单
最佳实践
- 在客户端实现缓存机制
- 监控剩余请求次数，接近限额时提醒用户
- 批量查询时添加延迟
- 合理规划请求频率
429 响应示例
{
"success": false,
"error": "请求次数已达今日上限",
"code": "RATE_LIMIT_EXCEEDED",
"rateLimit": {
"remaining": 0,
"limit": 150,
"reset": "2025-10-24T00:00:00.000Z"
}
}
超限后，您仍然可以看到配额重置时间。
IP 白名单
如果您需要更高的请求限额，可以申请加入 IP 白名单。
白名单特权
- 不受限制: 白名单 IP 不受每日 150 次限制
- 响应优先: 享有更高的服务优先级
- 适用场景: 高频查询、数据分析、批量处理等
申请条件
满足以下任一条件即可申请：
- 开源项目: 您的项目是开源的，使用本 API 提供公益服务
- 教育用途: 用于教学、学习或研究目的
- 商业合作: 需要大量调用 API 的商业项目
申请方式
请通过以下方式联系管理员：
- GitHub: 在项目仓库提交 Issue
- 邮箱: 发送申请邮件（包含项目介绍和使用场景）
申请时请提供：
- 您的固定 IP 地址
- 项目简介和用途说明
- 预估日请求量
- 项目网址（如有）
白名单 IP 响应
{
"success": true,
"data": { ... },
"rateLimit": {
"remaining": null,
"limit": null,
"reset": null
}
}
白名单 IP 的 rateLimit 字段为 null，表示不受限制。
监控配额使用
async function checkRateLimit() {
const response = await fetch(
'https://api.keykey.cc/api/public/memory-card?word=test'
)
const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'))
const limit = parseInt(response.headers.get('X-RateLimit-Limit'))
const reset = response.headers.get('X-RateLimit-Reset')
const percentage = (remaining / limit) * 100
console.log(`剩余请求: ${remaining}/${limit} (${percentage.toFixed(1)}%)`)
console.log(`重置时间: ${new Date(reset).toLocaleString()}`)
// 警告阈值
if (percentage < 10) {
console.warn('⚠️ 请求配额不足 10%！')
} else if (percentage < 20) {
console.warn('⚠️ 请求配额不足 20%')
}
return { remaining, limit, reset, percentage }
}
// 使用示例
const rateLimitStatus = await checkRateLimit()
常见问题
为什么我的配额消耗得特别快？
可能的原因：
- 您与其他用户共享同一个公网 IP（如公司网络、校园网）
- 没有实现客户端缓存，重复查询相同单词
- 批量查询时没有控制请求频率
建议实现本地缓存机制，避免重复请求。
配额什么时候重置？
配额在每天 UTC 0:00（北京时间早上 8:00）自动重置为 150 次。
您可以通过响应头 X-RateLimit-Reset 查看精确的重置时间。
150 次请求够用吗？
对于大多数使用场景，150 次/天是足够的：
- 个人学习使用：查询 50-100 个单词，配合缓存可用多天
- 小型应用：100-200 个活跃用户
- 开发测试：完全够用
如需更高配额，请申请白名单。
如何避免超限？
推荐的最佳实践：
- 实现客户端缓存（24小时）
- 监控
rateLimit.remaining字段 - 剩余次数 < 50 时提醒用户
- 批量查询时添加延迟（100-200ms）
- 在用户输入时使用防抖（debounce）