Errors & rate limits

This page describes the standard error format of the vario API, possible application codes, rate limits by plan, and recommendations for handling failures resiliently.

Standard error format

All errors return a JSON object with the following structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error."
  }
}

The code field is a stable English identifier that you can use in your error-handling logic. The message field is informational and may change between versions; do not depend on it for business logic.

Error code table

Rate limits by plan

Rate limits are applied per API key and measured over two windows: per minute and per day.

When the limit is reached, the server responds with 429 RATE_LIMIT_EXCEEDED and includes the Retry-After header with the seconds you should wait before retrying.

Resilience recommendations

Exponential backoff with jitter

When receiving a 429 or 503, do not retry immediately. Implement exponential backoff with a random component (jitter) to prevent multiple clients from hitting the server at the same time:

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

Monitor X-RateLimit-Remaining

If the X-RateLimit-Remaining header is present in the response, use it to anticipate limit exhaustion before receiving a 429. When the value is low, reduce the request cadence.

Mode strategy by volume

For large corpora, use mode=fast as the first pass. Reserve mode=full for texts that require deeper analysis. This reduces credit consumption and the risk of hitting the rate limit within short windows.

Analysis degradation

When the request does not include the Prefer: deep-analysis-required header, a deep analysis failure returns 200 with bedrock_available: false and a partial analysis. Check this field if you need to guarantee the full depth of analysis before making a decision.

Example: handling INSUFFICIENT_CREDITS error

import httpx

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

if response.status_code == 402:
    error = response.json()["error"]
    if error["code"] == "INSUFFICIENT_CREDITS":
        # Notify the team to top up credits
        raise InsufficientCreditsError("Credit top-up required.")