Requisições, paginação e limites

Envelopes JSON

Respostas bem-sucedidas de recurso único usam:

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

Listas adicionam campos de paginação:

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

Propriedades desconhecidas no corpo JSON são rejeitadas com unknown_field. Isso detecta erros de digitação em operações de escrita em vez de descartá-los silenciosamente.

Os parâmetros de consulta se comportam de maneira diferente: os não reconhecidos são ignorados, e não rejeitados. Ferramentas de análise e proxies costumam anexar os seus próprios parâmetros (utm_*, cf_*), e invalidar uma requisição válida por causa disso seria inadequado.

Padrões

Os valores padrão foram definidos para um uso interativo seguro. Por exemplo, o uso considera por padrão os últimos 30 dias e as traduções trazem por padrão 25 registros recentes e não arquivados. Um limite solicitado acima de 100 em listagens é limitado a 100.

Datas e carimbos de data/hora usam ISO 8601. Os nomes dos campos JSON estão em snake_case. Campos que ainda não são aplicáveis geralmente retornam null, mantendo a estrutura do recurso estável durante todo o ciclo de vida da tradução.

Paginação por cursor

Passe o valor de next_cursor de uma resposta para a requisição seguinte sem modificações. Interrompa quando ele for null ou quando has_more for 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);

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

Limites de taxa

Cada credencial tem um limite contínuo de 240 requisições por minuto e um pico máximo 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.

Todas as respostas contêm o cabeçalho RateLimit-Policy descrevendo ambas as janelas:

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

Ele informa apenas a política. Nenhuma contagem de requisições restantes é disponibilizada; portanto, controle o ritmo das requisições com base nos limites documentados e trate o erro 429 acompanhado de Retry-After como o sinal para desacelerar.

IDs de requisição e novas tentativas

Todas as respostas contêm um ID de requisição tanto no payload (request_id) quanto no cabeçalho X-Request-Id. Inclua-o ao entrar em contato com o suporte.

Tente novamente em caso de erros 429, 500, 502, 503 e 504 usando recuo exponencial (backoff) com variação aleatória (jitter). Não repita requisições com erros de validação, autenticação, permissão ou não encontrado (404) sem antes alterar o payload ou os parâmetros.

Barras no final da URL (trailing slashes) são toleradas. A API REST intencionalmente não envia permissões CORS para navegadores, pois as credenciais do workspace pertencem a código seguro executado no lado do servidor.