约定：响应信封、组别、分页与错误

把这些规则学一遍，所有端点的行为就都在你的预期之内。

响应信封

每个成功的响应都是包含两个键的 JSON 对象：

键	内容
data	对象（单个资源）或数组（列表）
meta	total、page、size、total_pages；端点不分页时，分页字段为 null

{
  "data": { "year": 2026, "status": "ACTIVE" },
  "meta": { "total": 1, "page": null, "size": null, "total_pages": null }
}

字段名全部使用 snake_case（rider_number、total_points、season_year）。

组别：MotoGP、Moto2 和 Moto3

按赛季划分的端点接受 category 查询参数，取值为 MOTOGP、MOTO2 或 MOTO3。class 是取值相同的别名，两者只需传其一，不要同时传。

GET /standings/seasons/2026/riders?category=MOTO2
GET /races/seasons/2026?category=MOTO3

请显式传入 category，让结果不依赖默认值。

分页

「获取全部」类端点（/riders、/teams、/races 和 /standings）通过 page（从 1 开始）和 size（1–200，默认 20）分页：

GET /riders?page=2&size=50

"meta": { "total": 118, "page": 2, "size": 50, "total_pages": 3 }

循环请求直到 page 达到 total_pages：

async function getAll(path) {
  const rows = [];
  for (let page = 1; ; page++) {
    const { data, meta } = await getEnvelope(`${path}?page=${page}&size=200`);
    rows.push(...data);
    if (!meta.total_pages || page >= meta.total_pages) return rows;
  }
}

/riders/seasons/{year} 这类按赛季划分的列表会在一次响应中返回整个赛季。

排序

积分榜按 position 排序返回。赛历和比赛结果不保证有序，请自行排序：

races.sort((a, b) => a.round_number - b.round_number);
results.sort((a, b) => a.position - b.position);

标识符

资源	查询方式
车手	比赛号码：/riders/{rider_number}（例如 93）
车队	任意车队列表中的不透明 ID：/teams/{id}，或按名称：/teams/name/{name}
比赛	赛季 + 轮次：/races/seasons/{year}/round/{round}，或不透明 ID：/races/{race_id}/results
赛季	年份：/seasons/{year}

不透明 ID（"82MQRdM5q7ub4OSm6Jhx"）请从列表响应中获取，不要写死；匹配车队时用 ID 而不是名称，因为赞助商名称每个赛季都会变。

积分榜类型

除了专用路由（/riders、/teams、/manufacturers、/bmw-m），你也可以按类型请求积分榜：

GET /standings/seasons/2026/type/MANUFACTURER?category=MOTOGP

类型有 RIDER、TEAM、MANUFACTURER 和 BMW_M。

错误

错误使用标准 HTTP 状态码和 JSON 响应体：

{
  "timestamp": "2026-01-27T19:18:29",
  "status": 404,
  "error": "Not Found",
  "message": "Rider not found with number: 99",
  "path": "/riders/99"
}

状态码	含义	处理方式
400	参数无效（年份错误、未知组别）	修正请求；若存在 validation_errors，其中会列出问题
401 / 403	RapidAPI 密钥缺失或无效，或未订阅	检查两个请求头和你的套餐
404	车手、车队、比赛或赛季不存在	显示「未找到」状态
429	已达到套餐的速率限制或配额	退避并稍后重试，或升级套餐
5xx	临时的服务器问题	使用指数退避重试；查看状态页

缓存

比赛结果和积分榜会在每个比赛周末之后变化，车手资料则在赛季之间变化。请积极缓存，以节省配额并保持页面快速：

数据	建议缓存时间
赛季、车手、车队、生涯统计	24 小时
赛历	12 小时
比赛结果和积分榜	比赛周末 1 小时，其余时间 12 小时

把密钥留在服务器端

RapidAPI 密钥是计费凭证。请从你的后端、无服务器函数或构建步骤调用 API，切勿在会把密钥发给用户的浏览器或移动端代码中调用。积分榜表格指南展示了一个带缓存的小型代理。