Requêtes, pagination et limites

Enveloppes JSON

Les réponses de réussite pour une ressource unique utilisent le format suivant :

{ "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 inconnues dans le corps JSON sont rejetées avec l’erreur unknown_field. Cela permet d’intercepter une faute de frappe lors d’une écriture au lieu de l’ignorer silencieusement.

Les paramètres de requête (query parameters) 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 leurs propres paramètres (utm_*, cf_*), et faire échouer une requête par ailleurs valide pour cette raison nuirait à l’expérience d’intégration.

Valeurs par défaut

Les valeurs par défaut sont choisies pour garantir une utilisation interactive sûre. Par exemple, les statistiques d’utilisation portent par défaut sur les 30 derniers jours et les traductions renvoient par défaut 25 enregistrements récents non archivés. Une limite de liste demandée supérieure à 100 est ramenée à 100.

Les dates et horodatages utilisent la norme ISO 8601. Les noms de champs JSON sont au format 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 la valeur de next_cursor d’une réponse à la requête suivante sans la modifier. Arrêtez-vous lorsqu’elle vaut null ou que has_more est 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);

Ne construisez pas et ne modifiez pas les curseurs. La pagination par curseur évite qu’une nouvelle traduction créée ne décale les lignes entre les pages.

Limites de débit

Chaque identifiant dispose d’une limite soutenue de 240 requêtes par minute et d’un plafond de rafale de 40 requêtes par tranche de 10 secondes. Une réponse 429 inclut l’en-tête Retry-After ; attendez le délai indiqué 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

Il indique uniquement la politique appliquée. Aucun décompte des requêtes restantes n’est publié ; cadencez donc vos requêtes en fonction des limites documentées et considérez le statut 429 accompagné de Retry-After comme le signal pour ralentir le rythme.

Identifiants de requête et nouvelles tentatives

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

Réessayez les erreurs 429, 500, 502, 503 et 504 avec un intervalle exponentiel et une variation aléatoire (jitter). Ne réessayez pas les erreurs de validation, d’authentification, d’autorisation ou de ressource introuvable sans modifier la requête au préalable.

Les barres obliques finales (trailing slashes) sont tolérées. L’API REST n’envoie délibérément aucune autorisation CORS pour navigateur, car les identifiants d’espace de travail doivent impérativement rester dans du code serveur de confiance.