Convenções: envelope, categorias, paginação e erros

Aprenda estas regras uma vez e todo endpoint se comportará como você espera.

O envelope de resposta

Toda resposta bem-sucedida é um objeto JSON com duas chaves:

Chave	Conteúdo
data	Um objeto (recurso único) ou um array (lista)
meta	total, page, size, total_pages — os campos de paginação são null quando o endpoint não é paginado

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

Os nomes de campos usam snake_case em toda a API (rider_number, total_points, season_year).

Categorias: MotoGP, Moto2 e Moto3

Os endpoints por temporada aceitam o parâmetro de query category com um destes valores: MOTOGP, MOTO2 ou MOTO3. class é um alias com os mesmos valores — envie um ou outro, não ambos.

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

Passe category explicitamente para que o resultado nunca dependa de um valor padrão.

Paginação

Os endpoints “get all” — /riders, /teams, /races e /standings — são paginados com page (a partir de 1) e size (1–200, padrão 20):

GET /riders?page=2&size=50

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

Repita até que page alcance 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;
  }
}

Listas por temporada, como /riders/seasons/{year}, retornam a temporada inteira em uma única resposta.

Ordenação

A classificação vem ordenada por position. Calendários e resultados de corridas não têm ordem garantida — ordene você mesmo:

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

Identificadores

Recurso	Busque por
Piloto	Número de corrida: /riders/{rider_number} (ex.: 93)
Equipe	ID opaco de qualquer lista de equipes: /teams/{id}, ou pelo nome: /teams/name/{name}
Corrida	Temporada + etapa: /races/seasons/{year}/round/{round}, ou ID opaco: /races/{race_id}/results
Temporada	Ano: /seasons/{year}

Obtenha IDs opacos ("82MQRdM5q7ub4OSm6Jhx") de uma resposta de lista em vez de fixá-los no código, e relacione equipes por ID, não por nome — os nomes de patrocinadores mudam de temporada para temporada.

Tipos de classificação

Além das rotas dedicadas (/riders, /teams, /manufacturers, /bmw-m), você pode pedir uma tabela de classificação por tipo:

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

Os tipos são RIDER, TEAM, MANUFACTURER e BMW_M.

Erros

Os erros usam códigos de status HTTP padrão e um corpo JSON:

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

Status	Significado	O que fazer
400	Parâmetro inválido (ano incorreto, categoria desconhecida)	Corrija a requisição; validation_errors lista os problemas quando presente
401 / 403	Chave RapidAPI ausente ou inválida, ou sem assinatura	Verifique os dois headers e o seu plano
404	O piloto, equipe, corrida ou temporada não existe	Mostre um estado de “não encontrado”
429	Limite de taxa ou cota do plano atingido	Aguarde e tente novamente mais tarde, ou faça upgrade do plano
5xx	Problema temporário no servidor	Tente novamente com backoff exponencial; consulte a página de status

Cache

Resultados e classificações mudam após cada fim de semana de corrida, e os perfis mudam entre temporadas. Use cache de forma agressiva para economizar cota e manter as páginas rápidas:

Dados	Tempo de cache sugerido
Temporadas, pilotos, equipes, estatísticas de carreira	24 horas
Calendário	12 horas
Resultados e classificação	1 hora em fins de semana de corrida, 12 horas nos demais dias

Mantenha sua chave no servidor

Sua chave RapidAPI é uma credencial de cobrança. Chame a API a partir do seu backend, de uma função serverless ou de uma etapa de build — nunca de código de navegador ou mobile que envie a chave aos usuários. O guia da tabela de classificação mostra um pequeno proxy com cache.