Todos os números, num lugar só

O teto por minuto conta toda requisição autenticada, numa janela móvel de 60 segundos — ela não zera na virada do relógio; drena conforme as chamadas antigas saem da janela. O teto por dia funciona igual, em 24 horas móveis, e conta só as requisições que consultam a fonte — leitura servida do acervo não gasta.

Nos planos com teto, toda resposta atendida traz os headers RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset referentes à janela por minuto — sua aplicação não precisa adivinhar quanto resta dela; o consumo do dia e do ciclo se consulta em GET /v1/usage, de custo zero. Estourar devolve 429 RATE_LIMITED com Retry-After e a janela que barrou em details.window.

A consulta que vai à fonte na hora pode voltar 429 com outro código, UPSTREAM_RATE_LIMITED. Ele não vem do seu plano: é o ritmo que o motor mantém com a fonte, somando todo o tráfego que vai até ela, ou a própria fonte pedindo uma pausa. A conduta é a mesma — esperar o Retry-After e repetir —, e a rotina abaixo trata os dois.

async function comRetentativa(fazerChamada, maxTentativas = 3) {
  for (let tentativa = 0; tentativa < maxTentativas; tentativa += 1) {
    const resposta = await fazerChamada();
    if (resposta.status !== 429) return resposta;

    // O 429 já diz quando tentar de novo — respeite-o em vez de adivinhar.
    const espera =
      Number(resposta.headers.get("retry-after") ?? 2 ** tentativa * 2);
    await new Promise((r) => setTimeout(r, espera * 1000));
  }
  throw new Error("Limite de vazão persistiu após as retentativas.");
}

A cota de créditos vale pelo ciclo de cobrança: a franquia do plano mais os pacotes avulsos ativos, contra o consumido e os pedidos assíncronos ainda em andamento — um job aceito já comprometeu o crédito dele. Estourar devolve 402 QUOTA_EXCEEDED com o extrato no corpo — e o webhook QUOTA_LOW avisa antes, aos 80% da franquia. Operações de custo zero continuam funcionando com a cota esgotada.

Além da cota da conta, cada chave pode ter um teto diário de créditos próprio — janela móvel de 24 horas, configurável no portal (até 1.000.000). Ele limita o estrago de uma credencial isolada sem parar as outras; estourar devolve 402 API_KEY_DAILY_CAP_EXCEEDED e as operações de custo zero seguem passando. Para conexões de agente de IA, o portal sugere 200 créditos/dia — um agente em loop não gasta o mês numa tarde.

Vigílias de texto (a busca salva que o motor repete todo dia): até 50 por conta, em qualquer plano — a 51ª responde 409. Elas não consomem créditos.

Colheita de jurisprudência sob demanda: um pedido cobre até 92 dias de janela (mais que isso é 400 de validação) e vira fatias — um dia de um tribunal ocupa 2 fatias. Os tetos de fatia são 30 por pedido e 300 por conta por dia; o excedente desses tetos volta recortado na resposta (campo rejected), nunca como erro. Só a fatia nova cobra 1 crédito: o que o acervo compartilhado já tem entra de graça.

A colheita corre em fila, ao longo do dia. A edição da última semana do diário, até a de ontem, vem primeiro, porque é o que acabou de sair; os dias pedidos vêm logo depois, à frente da colheita histórica do próprio motor. Um dia pedido que ainda está nessa semana corre junto com a edição.

Consulta servida do acervo custa menos porque não vai à fonte. O que decide é o frescor do dado, e a janela é a do seu plano: Starter serve do acervo o processo consultado há menos de 24 horas; Pro, 6 horas; Business, 1 hora; Enterprise, 15 minutos. Processo mais velho que a janela, a consulta revalida na fonte e cobra o preço cheio. A mesma escada dispara a atualização da série de publicações de um processo — em segundo plano, sem segurar a resposta.

O outro lado da moeda, dito com todas as letras: plano com janela mais curta revalida com mais frequência, então paga o preço cheio mais vezes na mesma rotina de consulta. É a troca — dado mais fresco por crédito.

Quando a fonte falha — demora demais, sai do ar ou pede para esperar — e o acervo guarda o processo, a consulta devolve a cópia guardada, com a data em que ela foi buscada, por 1 crédito, na ficha e no retrato com os movimentos. A resposta diz que é cópia e por que a fonte não respondeu; o que andou no processo depois dessa data não está nela. Por padrão, a API só usa a cópia de até 24 horas; para aceitar a de qualquer idade, peça com staleOnFailure=true. O canal para agentes de IA aceita sempre, e diz a data no texto. A cópia de mais de 24 horas só sai para quem já consultou o processo antes ou o acompanha; os demais recebem a falha da fonte. Quando a fonte responde que não tem o processo, isso não é falha: a resposta continua sendo a de processo não encontrado.

Para não depender de a fonte responder dentro da espera, a leitura pode seguir em segundo plano: POST /v1/processes/lookups responde na hora quando a fonte entrega e, quando ela falha, abre uma consulta que tenta sozinha por até 6 horas. Nada é cobrado enquanto ela tenta: o preço da leitura fica reservado e só é cobrado se o processo vier; se não vier, a reserva volta. Pedida com a cópia guardada, a consulta cobra 1 crédito pela cópia na hora e só o resto do preço quando a versão atual chega — as duas juntas custam o mesmo que a leitura direta.

A tabela completa de custos por operação está na página principal da documentação.