限速规则

公开记忆卡片 API 使用基于客户端 IP 的每日配额。

默认规则

  • Name
    每日配额
    Description
    每个 IP 150 个配额单位。
  • Name
    重置时间
    Description
    北京时间（Asia/Shanghai）每天 00:00。
  • Name
    单个查询
    Description

    每次 GET 请求消耗 1 个单位，包括 400 和 404 响应。

  • Name
    批量查询
    Description

    按需要访问数据库的词条数消耗；命中本地词典兜底的词条不计费。

  • Name
    超限响应
    Description
    返回 HTTP 429，不再继续消耗配额。
多个设备或用户共享同一个公网 IP 时，也会共享同一份公开 API 配额。

响应头

curl -I 'https://api.keykey.im/api/public/memory-card?word=hello'

# X-RateLimit-Limit: 150
# X-RateLimit-Remaining: 149
# X-RateLimit-Reset: 2026-08-24T16:00:00.000Z
  • Name
    X-RateLimit-Limit
    Type
    integer
    Description

    每日总配额。

  • Name
    X-RateLimit-Remaining
    Type
    integer
    Description

    本次请求完成后的剩余配额。

  • Name
    X-RateLimit-Reset
    Type
    string
    Description

    下一次北京时间 00:00，对应的 ISO 8601 时间。

单个查询与批量查询

单个查询会在参数校验前占用 1 个单位，因此无效的 word 也会计入配额。批量接口会先校验请求，再检查剩余配额并一次性扣除实际计费词数。

批量配额不足

{
  "success": false,
  "error": "配额不足：需要 20 次，剩余 10 次",
  "code": "INSUFFICIENT_QUOTA",
  "rateLimit": {
    "remaining": 10,
    "limit": 150,
    "reset": "2026-08-24T16:00:00.000Z"
  }
}

监控配额

async function getMemoryCard(word) {
  const params = new URLSearchParams({
    word,
    lang: 'en',
    includeLocalDictionaryFallback: 'true',
  })
  const response = await fetch(
    `https://api.keykey.im/api/public/memory-card?${params}`,
  )

  const remaining = Number(response.headers.get('X-RateLimit-Remaining'))
  const limit = Number(response.headers.get('X-RateLimit-Limit'))
  const reset = response.headers.get('X-RateLimit-Reset')

  if (Number.isFinite(remaining) && remaining < 20) {
    console.warn(`公开 API 配额剩余 ${remaining}/${limit}，将在 ${reset} 重置`)
  }

  return response.json()
}

降低配额消耗

  1. 对多词查询使用 /api/public/memory-card/batch-query。
  2. 在合适的业务场景启用 includeLocalDictionaryFallback=true。
  3. API 本身返回 Cache-Control: no-store；如业务允许，可在客户端或服务端建立带版本失效策略的自有缓存。
  4. 避免在输入变化时立即请求；在用户提交或防抖后再查询。

白名单

服务端可为固定 IP 配置白名单。白名单请求不受每日 150 次限制；JSON 中的无限值会表现为 null，精确策略以响应头和服务端配置为准。

超限处理

{
  "success": false,
  "error": "请求次数已达今日上限",
  "code": "RATE_LIMIT_EXCEEDED",
  "rateLimit": {
    "remaining": 0,
    "limit": 150,
    "reset": "2026-08-24T16:00:00.000Z"
  }
}

收到 429 后，应停止自动重试并等待 rateLimit.reset。服务器错误或网络错误才适合使用有上限的指数退避。

Was this page helpful?