---
title: "Requêtes, pagination et limites"
description: "Construisez des clients API AI Glot prévisibles en utilisant des enveloppes de réponse, des paramètres stricts, la pagination par curseur, des ID de requête."
canonical: "https://ai-glot.com/docs/fr/api/conventions"
updated: "2026-08-12"
---

# Requêtes, pagination et limites

## Enveloppes JSON

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

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

Les listes ajoutent des champs de pagination :

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

> **Warning**
>
> Un nom de filtre mal orthographié dans une chaîne de requête est ignoré silencieusement, et la requête renvoie toujours un code `200` avec une page non filtrée. Vérifiez l'orthographe des paramètres dans la référence des points de terminaison plutôt que de vous fier à une réponse réussie.

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

```js title="Lister toutes les traductions"
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 :

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