Requisições, paginação e limites

Envelopes JSON

Respostas bem-sucedidas de recurso único utilizam:

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

Listas adicionam campos de paginação:

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

Propriedades de corpo JSON desconhecidas são rejeitadas com unknown_field. Isso detecta um erro de digitação em uma operação de escrita em vez de descartá-lo silenciosamente.

Parâmetros de consulta (query parameters) comportam-se de forma diferente: os não reconhecidos são ignorados, não rejeitados. Ferramentas de análise e proxies frequentemente adicionam seus próprios parâmetros (utm_*, cf_*), e falhar em uma requisição válida por causa de um deles seria contraproducente.

Padrões (Defaults)

Os padrões são escolhidos para um uso interativo seguro. Por exemplo, o uso padrão é dos últimos 30 dias e as traduções padrão são as 25 mais recentes e não arquivadas. Um limite de lista solicitado acima de 100 é limitado a 100.

Datas e timestamps utilizam ISO 8601. Os nomes dos campos JSON estão em snake_case. Campos que ainda não são aplicáveis são geralmente null para que a estrutura do recurso permaneça estável durante o ciclo de vida de uma tradução.

Paginação por cursor

Passe o next_cursor de uma resposta para a próxima requisição sem alterações. Pare quando ele for null ou has_more for falso.

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);

Não construa nem modifique cursores. A paginação por cursor evita que uma tradução recém-criada desloque linhas entre as páginas.

Limites de taxa (Rate limits)

Cada credencial possui um limite sustentado de 240 requisições por minuto e um teto de pico (burst) de 40 requisições a cada 10 segundos. Uma resposta 429 inclui o cabeçalho Retry-After; aguarde o tempo indicado antes de tentar novamente.

Cada resposta carrega um cabeçalho RateLimit-Policy descrevendo ambas as janelas:

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

Ele indica apenas a política. Nenhuma contagem de requisições restantes é publicada, portanto, cadencie as requisições de acordo com os limites documentados e trate o erro 429 junto ao Retry-After como o sinal para reduzir a frequência.

IDs de requisição e tentativas (Retries)

Cada resposta carrega um ID de requisição tanto no payload (request_id) quanto no cabeçalho X-Request-Id. Inclua-o ao solicitar suporte.

Tente novamente erros 429, 500, 502, 503 e 504 usando backoff exponencial e jitter. Não tente novamente erros de validação, autenticação, permissão ou de recurso não encontrado (not-found) sem alterar a requisição.

Barras finais (trailing slashes) são toleradas. A API REST intencionalmente não envia permissões CORS de navegador porque as credenciais de workspace devem residir em código confiável do lado do servidor.