---
title: "Richieste, paginazione e limiti"
description: "Sviluppa client API di AI Glot prevedibili utilizzando envelope di risposta, parametri rigorosi, paginazione tramite cursore, ID richiesta."
canonical: "https://ai-glot.com/docs/it/api/conventions"
updated: "2026-08-12"
---

# Richieste, paginazione e limiti

## Envelope JSON

Le risposte di successo per una singola risorsa utilizzano:

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

Gli elenchi aggiungono i campi di paginazione:

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

Le proprietà del corpo JSON sconosciute vengono rifiutate con `unknown_field`. Questo permette di intercettare un refuso in un'operazione di scrittura invece di scartarlo silenziosamente.

I parametri di query si comportano diversamente: quelli non riconosciuti vengono ignorati, non rifiutati. Strumenti di analisi e proxy aggiungono regolarmente i propri (`utm_*`, `cf_*`), e far fallire una richiesta altrimenti valida a causa di uno di questi sarebbe controproducente.

> **Warning**
>
> Un nome di filtro scritto in modo errato in una query string viene ignorato silenziosamente e la richiesta restituisce comunque un `200` con una pagina non filtrata. Verifica l'ortografia dei parametri facendo riferimento alla documentazione dell'endpoint, anziché fidarti di una risposta riuscita.

## Valori predefiniti

I valori predefiniti sono scelti per un uso interattivo sicuro. Ad esempio, l'utilizzo è impostato predefautemente sugli ultimi 30 giorni e le traduzioni su 25 record recenti e non archiviati. Un limite di elenco richiesto superiore a 100 viene bloccato a 100.

Date e timestamp utilizzano lo standard ISO 8601. I nomi dei campi JSON sono in `snake_case`. I campi non ancora applicabili sono solitamente `null`, così che la struttura della risorsa rimanga stabile durante l'intero ciclo di vita di una traduzione.

## Paginazione tramite cursore

Passa il `next_cursor` di una risposta nella richiesta successiva senza modificarlo. Fermati quando è `null` o quando `has_more` è false.

```js title="Elenca ogni traduzione"
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);
```

Non costruire né modificare i cursori. La paginazione tramite cursore evita che una traduzione appena creata sposti le righe tra le pagine.

## Rate limit

Ogni credenziale ha un limite sostenuto di **240 richieste al minuto** e un limite di picco (burst) di **40 richieste ogni 10 secondi**. Una risposta `429` include l'header `Retry-After`; attendi l'intervallo indicato prima di riprovare.

Ogni risposta include un header `RateLimit-Policy` che descrive entrambe le finestre:

```http title="RateLimit-Policy"
RateLimit-Policy: 240;w=60, 40;w=10
```

Questo indica solo la policy. Non viene pubblicato il conteggio delle richieste rimanenti, quindi regola il ritmo delle richieste in base ai limiti documentati e considera il `429` insieme al `Retry-After` come segnale per rallentare.

## ID richiesta e tentativi di riinvio

Ogni risposta contiene un ID richiesta sia nel payload (`request_id`) che nell'header `X-Request-Id`. Includilo quando richiedi assistenza.

Riprova le risposte `429`, `500`, `502`, `503` e `504` utilizzando l'exponential backoff e il jitter. Non riprovare gli errori di validazione, autenticazione, permessi o errori "not found" senza modificare la richiesta.

Gli slash finali sono tollerati. L'API REST non invia intenzionalmente permessi CORS del browser perché le credenziali di workspace devono risiedere in codice server affidabile.