Errores y rate limits

Esta página describe el formato estándar de error de la API de vario, los códigos de aplicación posibles, los límites de tasa por plan y las recomendaciones para manejar fallos de manera resiliente.

Formato de error estándar

Todos los errores retornan un objeto JSON con la siguiente estructura:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Descripción legible del error."
  }
}

El campo code es un identificador estable en inglés que puedes usar en tu lógica de manejo de errores. El campo message es orientativo y puede cambiar entre versiones; no dependas de él para lógica de negocio.

Tabla de códigos de error

Rate limits por plan

Los límites de tasa se aplican por API key y se miden en dos ventanas: por minuto y por día.

Cuando se alcanza el límite, el servidor responde con 429 RATE_LIMIT_EXCEEDED e incluye el header Retry-After con los segundos que debes esperar antes de reintentar.

Recomendaciones de resiliencia

Backoff exponencial con jitter

Al recibir un 429 o un 503, no reintentes inmediatamente. Implementa un backoff exponencial con componente aleatorio (jitter) para evitar que múltiples clientes golpeen el servidor al mismo tiempo:

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

Monitorear X-RateLimit-Remaining

Si el header X-RateLimit-Remaining está presente en la respuesta, úsalo para anticipar el agotamiento del límite antes de recibir un 429. Cuando el valor sea bajo, reduce la cadencia de requests.

Estrategia de modo por volumen

Para corpus masivos, usa mode=fast como primera pasada. Reserva mode=full para los textos que requieran análisis más profundo. Esto reduce el consumo de créditos y el riesgo de alcanzar el rate limit en ventanas cortas.

Degradación del análisis

Cuando el request no incluye el header Prefer: deep-analysis-required, un fallo del análisis profundo retorna 200 con bedrock_available: false y un análisis parcial. Verifica este campo si necesitas garantizar la profundidad completa del análisis antes de tomar una decisión.

Ejemplo: manejo de error INSUFFICIENT_CREDITS

import httpx

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

if response.status_code == 402:
    error = response.json()["error"]
    if error["code"] == "INSUFFICIENT_CREDITS":
        # Notificar al equipo para recargar créditos
        raise InsufficientCreditsError("Recarga de créditos requerida.")