---
title: "Requisições, paginação e limites"
description: "Construa clientes de API do AI Glot previsíveis usando envelopes de resposta, parâmetros rigorosos, paginação por cursor, IDs de requisição, limites de taxa e tentativas."
canonical: "https://ai-glot.com/docs/pt/api/conventions"
updated: "2026-08-12"
---

# Requisições, paginação e limites

## Envelopes JSON

Respostas bem-sucedidas de recurso único utilizam:

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

Listas adicionam campos de paginação:

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

> **Warning**
>
> Um nome de filtro digitado incorretamente em uma query string é ignorado silenciosamente, e a requisição ainda retorna `200` com uma página não filtrada. Verifique a ortografia dos parâmetros na referência do endpoint em vez de confiar apenas em uma resposta bem-sucedida.

## 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.

```js title="Listar todas as traduções"
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:

```http title="RateLimit-Policy"
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.