Richieste, paginazione e limiti

Envelope JSON

Le risposte di successo per una singola risorsa utilizzano:

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

Gli elenchi aggiungono i campi di paginazione:

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

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.

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:

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.