Richieste, paginazione e limiti

Envelope JSON

Le risposte con esito positivo per una singola risorsa utilizzano la struttura:

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

Gli elenchi aggiungono i campi dedicati alla paginazione:

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

Le proprietà sconosciute nel corpo JSON vengono rifiutate con l’errore unknown_field. Ciò consente di rilevare tempestivamente un refuso in un’operazione di scrittura anziché ignorarlo silenziosamente.

I parametri di query si comportano diversamente: quelli non riconosciuti vengono ignorati e non rifiutati. Gli strumenti di analisi e i proxy ne aggiungono abitualmente di propri (utm_*, cf_*), e far fallire una richiesta altrimenti valida a causa di questi risulterebbe problematico.

Valori predefiniti

I valori predefiniti sono impostati per garantire un utilizzo interattivo e sicuro. Ad esempio, i dati sull’utilizzo fanno riferimento per impostazione predefinita agli ultimi 30 giorni e le traduzioni a 25 record recenti non archiviati. Se viene richiesto un limite di elenco superiore a 100, questo viene automaticamente limitato a 100.

Date e timestamp utilizzano il formato ISO 8601. I nomi dei campi JSON sono in snake_case. I campi non ancora applicabili sono generalmente impostati su null, in modo che la struttura delle risorse rimanga stabile durante tutto il ciclo di vita di una traduzione.

Paginazione basata su cursore

Passa il valore next_cursor ottenuto da una risposta alla richiesta successiva senza modificarlo. Interrompi le chiamate quando è null oppure quando has_more è 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);

Non costruire né modificare manualmente i cursori. La paginazione a cursore impedisce che una traduzione appena creata provochi lo slittamento delle righe da una pagina all’altra.

Limiti di frequenza (rate limits)

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 il tempo specificato prima di ritentare.

Ogni risposta include l’header RateLimit-Policy che descrive entrambe le finestre:

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

Questo header specifica unicamente i criteri applicati. Non viene pubblicato il conteggio delle richieste rimanenti, pertanto regola il ritmo delle richieste in base ai limiti documentati e considera il codice 429 unitamente a Retry-After come il segnale per ridurre la frequenza.

ID di richiesta e tentativi di retry

Ogni risposta include un ID di richiesta sia nel payload (request_id) che nell’header X-Request-Id. Includilo sempre quando contatti il supporto.

Esegui nuovamente i tentativi per gli errori 429, 500, 502, 503 e 504 applicando un backoff esponenziale con jitter. Non ritentare gli errori di convalida, autenticazione, autorizzazione o risorsa non trovata senza aver prima corretto la richiesta.

Le barre finali (trailing slash) negli URL sono tollerate. L’API REST non invia intenzionalmente permessi CORS per il browser, in quanto le credenziali dello spazio di lavoro devono essere utilizzate esclusivamente in codice attendibile lato server.