Erros e rate limits

Esta página descreve o formato padrão de erro da API do vario, os códigos de aplicação possíveis, os limites de taxa por plano e as recomendações para lidar com falhas de forma resiliente.

Formato padrão de erro

Todos os erros retornam um objeto JSON com a seguinte estrutura:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Descrição legível do erro."
  }
}

O campo code é um identificador estável em inglês que você pode usar na sua lógica de tratamento de erros. O campo message é informativo e pode mudar entre versões; não dependa dele para lógica de negócio.

Tabela de códigos de erro

Rate limits por plano

Os limites de taxa são aplicados por API key e medidos em duas janelas: por minuto e por dia.

Quando o limite é atingido, o servidor responde com 429 RATE_LIMIT_EXCEEDED e inclui o header Retry-After com os segundos que você deve aguardar antes de retentar.

Recomendações de resiliência

Backoff exponencial com jitter

Ao receber um 429 ou um 503, não retente imediatamente. Implemente um backoff exponencial com componente aleatório (jitter) para evitar que múltiplos clientes atinjam o servidor ao mesmo tempo:

import time
import random

def call_with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        response = fn()
        if response.status_code not in (429, 503):
            return response
        retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
        sleep_time = retry_after + random.uniform(0, 1)
        time.sleep(sleep_time)
    raise Exception("Max retries exceeded")

Monitorar X-RateLimit-Remaining

Se o header X-RateLimit-Remaining estiver presente na resposta, use-o para antecipar o esgotamento do limite antes de receber um 429. Quando o valor estiver baixo, reduza a cadência de requisições.

Estratégia de modo por volume

Para corpora massivos, use mode=fast como primeira passagem. Reserve mode=full para os textos que exigirem análise mais profunda. Isso reduz o consumo de créditos e o risco de atingir o rate limit em janelas curtas.

Degradação da análise

Quando a requisição não inclui o header Prefer: deep-analysis-required, uma falha na análise profunda retorna 200 com bedrock_available: false e uma análise parcial. Verifique esse campo se precisar garantir a profundidade completa da análise antes de tomar uma decisão.

Exemplo: tratamento do erro INSUFFICIENT_CREDITS

import httpx

response = httpx.post(
    "https://api.vario.lat/v1/analyze",
    headers={"Authorization": "Bearer vario_SUA_API_KEY"},
    json={"text": "...", "playbook": "price_fixing", "language": "pt"}
)

if response.status_code == 402:
    error = response.json()["error"]
    if error["code"] == "INSUFFICIENT_CREDITS":
        # Notificar a equipe para recarregar créditos
        raise InsufficientCreditsError("Recarga de créditos necessária.")