Solicitudes, paginación y límites

Envoltorios JSON

Las respuestas exitosas de un recurso único utilizan:

{ "data": {}, "request_id": "req_example" }

Las listas añaden campos de paginación:

{
  "data": [],
  "has_more": true,
  "next_cursor": "opaque-cursor",
  "request_id": "req_example"
}

Las propiedades del cuerpo JSON desconocidas son rechazadas con unknown_field. Esto permite detectar una errata en una escritura en lugar de descartarla silenciosamente.

Los parámetros de consulta se comportan de forma diferente: los no reconocidos se ignoran, no se rechazan. Las herramientas de análisis y los proxies suelen añadir los suyos propios (utm_*, cf_*), y hacer fallar una solicitud que de otro modo sería válida por motivo de uno de ellos sería contraproducente.

Valores predeterminados

Los valores predeterminados se han elegido para un uso interactivo seguro. Por ejemplo, el uso se limita por defecto a los últimos 30 días y las traducciones a los 25 registros recientes no archivados. Un límite de lista solicitado superior a 100 se ajusta automáticamente a 100.

Las fechas y marcas de tiempo utilizan el estándar ISO 8601. Los nombres de los campos JSON utilizan snake_case. Los campos que aún no son aplicables suelen ser null para que la estructura del recurso se mantenga estable a lo largo del ciclo de vida de una traducción.

Paginación por cursor

Pase el next_cursor de una respuesta a la siguiente solicitud sin cambios. Deténgase cuando sea null o cuando has_more sea falso.

let cursor;
do {
  const url = new URL('https://api.ai-glot.com/v1/batches');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);

  const page = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.AIGLOT_API_KEY}` },
  }).then(response => response.json());

  for (const translation of page.data) console.log(translation.id);
  cursor = page.next_cursor;
} while (cursor);

No construya ni modifique los cursores. La paginación por cursor evita que una traducción recién creada desplace las filas entre páginas.

Límites de tasa (Rate limits)

Cada credencial tiene un límite sostenido de 240 solicitudes por minuto y un techo de ráfaga de 40 solicitudes cada 10 segundos. Una respuesta 429 incluye la cabecera Retry-After; espere el tiempo indicado antes de reintentar.

Cada respuesta incluye una cabecera RateLimit-Policy que describe ambas ventanas:

RateLimit-Policy: 240;w=60, 40;w=10

Esta cabecera indica únicamente la política. No se publica el recuento de solicitudes restantes, por lo que debe cadenciar las solicitudes según los límites documentados y tratar el error 429 junto con Retry-After como la señal para reducir la frecuencia.

IDs de solicitud y reintentos

Cada respuesta lleva un ID de solicitud tanto en el cuerpo (request_id) como en la cabecera X-Request-Id. Inclúyalo cuando solicite asistencia técnica.

Reintente los errores 429, 500, 502, 503 y 504 utilizando un retroceso exponencial (exponential backoff) y jitter. No reintente errores de validación, autenticación, permisos o de recurso no encontrado sin modificar la solicitud.

Se toleran las barras diagonales finales (trailing slashes). La API REST no envía intencionadamente permisos CORS de navegador porque las credenciales del espacio de trabajo deben residir en código seguro del lado del servidor.