Errors

Errors are returned as application/problem+json (RFC 9457). Branch on the code field, never on the human-readable detail string — code is stable, detail is not.

Shape

{
  "type": "https://vizvuz.com/docs/errors#quota_exceeded",
  "title": "Quota exceeded",
  "status": 402,
  "code": "quota_exceeded",
  "detail": "Monthly character quota exhausted and the overage cap is reached.",
  "request_id": "01J8ZC4M9XK3P7QW2NRT5V6YAB"
}

Some errors add fields — rate_limited adds limit, quota_exceeded adds character_limit, overage_cap_minor and period_end. Ignore fields you do not know.

Codes

Which errors are worth retrying

Failed requests are not billed. A 429 and a 503 cost nothing, and a rolled-back reservation returns the characters to your quota or credit immediately.

A retry loop that behaves

import time, requests

def translate(payload, key, attempts=4):
    for attempt in range(attempts):
        response = requests.post(
            "https://api.vizvuz.com/v1/translate",
            headers={"Authorization": f"Bearer {key}"},
            json=payload,
            timeout=35,
        )
        if response.status_code < 400:
            return response.json()
        problem = response.json()
        if problem["code"] not in ("rate_limited", "engine_unavailable", "internal_error"):
            raise RuntimeError(f"{problem['code']}: {problem['detail']}")
        wait = float(response.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait)
    raise RuntimeError("giving up after retries")

Always log the request id

Every response — successful or not — carries X-Request-Id. Log it next to your own correlation id. With it we can find a single request in seconds; without it, investigating a report means guessing.

What we never return

We never surface an error, header or message from the translation engine. Engine failures are logged internally without their payload and reported to you as engine_unavailable. Your text never appears in our logs.