Solicitudes, paginación y límites

Envoltorios JSON

Las respuestas satisfactorias de un único recurso utilizan la siguiente estructura:

{ "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 desconocidas en el cuerpo JSON se rechazan con unknown_field. Esto permite detectar errores tipográficos al escribir datos en lugar de descartarlos de forma silenciosa.

Los parámetros de consulta funcionan de manera diferente: los no reconocidos se ignoran, no se rechazan. Las herramientas de analítica y los servidores proxy suelen añadir sus propios parámetros (utm_*, cf_*), y rechazar una solicitud válida por este motivo resultaría perjudicial.

Valores predeterminados

Los valores predeterminados se eligen para un uso interactivo seguro. Por ejemplo, el uso se establece por defecto en los últimos 30 días y las traducciones se limitan por defecto a 25 registros recientes no archivados. Si se solicita un límite de lista superior a 100, se acotará a 100.

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

Paginación por cursor

Pasa el valor de next_cursor de una respuesta a la siguiente solicitud sin modificarlo. Detén las solicitudes cuando sea null o cuando has_more sea false.

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 construyas ni modifiques los cursores manualmente. La paginación por cursor evita que una traducción recién creada desplace filas entre diferentes páginas.

Límites de frecuencia

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

Todas las respuestas incluyen una cabecera RateLimit-Policy que describe ambas ventanas:

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

Solo indica la directiva aplicada. No se publica un recuento de solicitudes restantes, por lo que debes regular las solicitudes en función de los límites documentados y tomar la respuesta 429 junto con Retry-After como la señal para reducir el ritmo.

ID de solicitud y reintentos

Todas las respuestas incluyen un identificador de solicitud tanto en el cuerpo (request_id) como en la cabecera X-Request-Id. Inclúyelo siempre que te pongas en contacto con el servicio de soporte.

Reintenta los errores 429, 500, 502, 503 y 504 aplicando un retardo exponencial (exponential backoff) con variación aleatoria (jitter). No reintentes errores de validación, autenticación, permisos o de recurso no encontrado sin modificar la solicitud previamente.

Se admiten barras finales en las URL. La API REST no envía deliberadamente permisos CORS para navegadores, ya que las credenciales del espacio de trabajo deben permanecer en código seguro del lado del servidor.