Requêtes, pagination et limites

Enveloppes JSON

Les réponses réussies pour une ressource unique utilisent :

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

Les listes ajoutent des champs de pagination :

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

Les propriétés de corps JSON inconnues sont rejetées avec l’erreur unknown_field. Cela permet de détecter une faute de frappe lors d’une écriture plutôt que de l’ignorer silencieusement.

Les paramètres de requête se comportent différemment : ceux qui ne sont pas reconnus sont ignorés et non rejetés. Les outils d’analyse et les proxys ajoutent couramment les leurs (utm_*, cf_*), et faire échouer une requête par ailleurs valide à cause de l’un d’eux serait contre-productif.

Valeurs par défaut

Les valeurs par défaut sont choisies pour un usage interactif sécurisé. Par exemple, l’utilisation par défaut s’étend aux 30 derniers jours et les traductions affichent par défaut les 25 enregistrements récents non archivés. Une limite de liste demandée supérieure à 100 est plafonnée à 100.

Les dates et les horodatages utilisent la norme ISO 8601. Les noms de champs JSON sont en snake_case. Les champs qui ne sont pas encore applicables sont généralement null afin que la structure des ressources reste stable tout au long du cycle de vie d’une traduction.

Pagination par curseur

Transmettez le next_cursor d’une réponse dans la requête suivante sans modification. Arrêtez-vous lorsque celui-ci est null ou que has_more est faux.

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);

Ne construisez pas et ne modifiez pas les curseurs. La pagination par curseur empêche une traduction nouvellement créée de décaler les lignes entre les pages.

Limites de débit (Rate limits)

Chaque identifiant a une limite soutenue de 240 requêtes par minute et un plafond de pointe de 40 requêtes par 10 secondes. Une réponse 429 inclut l’en-tête Retry-After ; attendez la fin de ce délai avant de réessayer.

Chaque réponse comporte un en-tête RateLimit-Policy décrivant les deux fenêtres :

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

Celui-ci indique uniquement la politique. Aucun décompte des requêtes restantes n’est publié ; cadencez donc vos requêtes selon les limites documentées et considérez le code 429 accompagné du Retry-After comme le signal pour ralentir.

ID de requête et tentatives

Chaque réponse comporte un ID de requête, à la fois dans le corps (request_id) et dans l’en-tête X-Request-Id. Communiquez-le lorsque vous sollicitez le support.

Réessayez les erreurs 429, 500, 502, 503 et 504 avec un backoff exponentiel et du jitter. Ne réessayez pas les erreurs de validation, d’authentification, de permission ou les erreurs « non trouvé » sans modifier la requête.

Les barres obliques finales (trailing slashes) sont tolérées. L’API REST n’envoie intentionnellement aucune autorisation CORS pour le navigateur, car les identifiants d’espace de travail doivent résider dans un code serveur sécurisé.