---
title: "Solicitudes, paginación y límites"
description: "Cree clientes de la API de AI Glot predecibles utilizando envoltorios de respuesta, parámetros estrictos, paginación por cursor, IDs de solicitud."
canonical: "https://ai-glot.com/docs/es/api/conventions"
updated: "2026-08-12"
---

# Solicitudes, paginación y límites

## Envoltorios JSON

Las respuestas exitosas de un recurso único utilizan:

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

Las listas añaden campos de paginación:

```json
{
  "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.

> **Warning**
>
> Un nombre de filtro mal escrito en una cadena de consulta se ignora silenciosamente y la solicitud sigue devolviendo un `200` con una página sin filtrar. Verifique la ortografía de los parámetros en la referencia del endpoint en lugar de confiar en una respuesta exitosa.

## 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.

```js title="Listar todas las traducciones"
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:

```http title="RateLimit-Policy"
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.