Convenciones: envoltorio, categorías, paginación y errores

Aprende estas reglas una vez y cada endpoint se comportará como esperas.

El envoltorio de respuesta

Toda respuesta correcta es un objeto JSON con dos claves:

Clave	Contenido
data	Un objeto (recurso único) o un array (lista)
meta	total, page, size, total_pages — los campos de paginación son null cuando el endpoint no está paginado

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

Los nombres de campo son snake_case en todas partes (rider_number, total_points, season_year).

Categorías: MotoGP, Moto2 y Moto3

Los endpoints por temporada aceptan un parámetro de consulta category con uno de estos valores: MOTOGP, MOTO2 o MOTO3. class es un alias con los mismos valores — envía uno u otro, no ambos.

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

Pasa category de forma explícita para que el resultado nunca dependa de un valor por defecto.

Paginación

Los endpoints de «obtener todo» — /riders, /teams, /races y /standings — se paginan con page (desde 1) y size (1–200, por defecto 20):

GET /riders?page=2&size=50

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

Itera hasta 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;
  }
}

Las listas por temporada, como /riders/seasons/{year}, devuelven toda la temporada en una sola respuesta.

Orden

Las clasificaciones llegan ordenadas por position. Los calendarios y los resultados de carrera no tienen orden garantizado — ordénalos tú mismo:

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

Identificadores

Recurso	Se consulta por
Piloto	Número de carrera: /riders/{rider_number} (p. ej. 93)
Equipo	ID opaco de cualquier lista de equipos: /teams/{id}, o por nombre: /teams/name/{name}
Carrera	Temporada + ronda: /races/seasons/{year}/round/{round}, o ID opaco: /races/{race_id}/results
Temporada	Año: /seasons/{year}

Toma los ID opacos ("82MQRdM5q7ub4OSm6Jhx") de una respuesta de lista en lugar de fijarlos en el código, y relaciona los equipos por ID y no por nombre — los nombres de los patrocinadores cambian de una temporada a otra.

Tipos de clasificación

Además de las rutas dedicadas (/riders, /teams, /manufacturers, /bmw-m), puedes pedir una tabla de clasificación por tipo:

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

Los tipos son RIDER, TEAM, MANUFACTURER y BMW_M.

Errores

Los errores usan códigos de estado HTTP estándar y un cuerpo JSON:

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

Estado	Significado	Qué hacer
400	Parámetro no válido (año incorrecto, categoría desconocida)	Corrige la petición; validation_errors lista los problemas cuando está presente
401 / 403	Clave de RapidAPI ausente o no válida, o sin suscripción	Revisa ambas cabeceras y tu plan
404	El piloto, equipo, carrera o temporada no existe	Muestra un estado de «no encontrado»
429	Se alcanzó el límite de peticiones o la cuota de tu plan	Espera y reintenta más tarde, o mejora el plan
5xx	Problema temporal del servidor	Reintenta con retroceso exponencial; consulta la página de estado

Caché

Los resultados y las clasificaciones cambian después de cada fin de semana de carrera, y los perfiles entre temporadas. Usa la caché a fondo para ahorrar cuota y mantener las páginas rápidas:

Datos	Tiempo de caché sugerido
Temporadas, pilotos, equipos, estadísticas de carrera	24 horas
Calendario	12 horas
Resultados y clasificaciones	1 hora en fines de semana de carrera, 12 horas el resto del tiempo

Mantén tu clave en el servidor

Tu clave de RapidAPI es una credencial de facturación. Llama a la API desde tu backend, una función serverless o un paso de build — nunca desde código de navegador o móvil que entregue la clave a los usuarios. La guía de la tabla de clasificación muestra un pequeño proxy con caché.