Errors

Every non-2xx response has the same JSON shape — the OpenAI standard. Match on error.code for programmatic handling, on status_code for retry policy.

Error payload

{
  "error": {
    "message": "Model 'xyz-2025' is not available",
    "type": "model_not_found",
    "code": "model_not_found",
    "param": null
  }
}

HTTP status codes

Common error codes

authentication_error

• Forgot to set Authorization: Bearer ... header.
• API key was revoked from /app/keys.
• Key still has wrong prefix (must start with sk-kn-).

insufficient_quota

• Wallet balance too low for this request → error.code is insufficient_balance, and the error carries what the wallet held (balance_usd), what this request reserves (needed_usd), and two links: topup_url opens the billing page with a top-up preselected, auto_recharge_url opens it on the auto-recharge settings. Neither link charges anything by itself.
• Per-key monthly cap reached. Reset is at calendar month start (UTC). Raise the cap at /app/keys.

{
  "error": {
    "message": "Wallet balance is too low for this request. Top up at https://kunavo.com/app/billing — or turn on auto-recharge there, and a saved card refills the wallet before requests are refused.",
    "type": "insufficient_quota",
    "code": "insufficient_balance",
    "param": null,
    "balance_usd": 0.0142,
    "needed_usd": 0.0381,
    "topup_url": "https://kunavo.com/app/billing?topup=20",
    "auto_recharge_url": "https://kunavo.com/app/billing?autorecharge=1&src=api_402"
  }
}

Stop retrying on insufficient_balance unless the response has a Retry-After header — that one means an auto-recharge is already charging your saved card, and the same request should succeed a few seconds later.

permission_error

• The key carries an IP allowlist and your call came from an address outside it. The message names the address we saw — add it (or its CIDR block) at /app/keys, or drop the allowlist entirely to allow any address.
• Moving an agent to a new host, a new NAT gateway, or a laptop on a different network all change that address. A key with no allowlist is never refused this way.

model_not_found

• Misspelled slug. Use /models for the canonical list.
• Model is currently disabled (upstream outage or pricing review).

upstream_error

Indicates an upstream model provider returned an error that we couldn't translate to a more specific code. Body includes the original message. Common causes:

• Provider-side overload.
• Content moderation rejection (try a different prompt).
• Region / availability gating.

Retry strategy

The simplest robust pattern: exponential backoff with jitter on 429 / 5xx only.

import time, random
from openai import OpenAI, RateLimitError, APIError

client = OpenAI(api_key=os.environ["KUNAVO_API_KEY"], base_url="https://api.kunavo.com/v1")

def call_with_retry(call, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return call()
        except RateLimitError:
            if attempt + 1 == max_attempts: raise
            # 429: exponential backoff with jitter
            time.sleep(min(2 ** attempt, 30) + random.random())
        except APIError as e:
            if e.status_code and 500 <= e.status_code < 600 and attempt + 1 < max_attempts:
                time.sleep(min(2 ** attempt, 30) + random.random())
            else:
                raise

result = call_with_retry(lambda: client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "hi"}],
))

• Cap the wait at 30 seconds per attempt and the total at 5 attempts.
• Don't retry 4xx (except 408 and 429). Doing so just burns time.
• For idempotent endpoints (image / video generation), retries are safe — failed calls were never billed.
• For chat with side effects in your own code, deduplicate via an idempotency key in your application layer.

Debugging from the dashboard

Every API call — successful or failed — is visible at /app/usage. Click any row for the full request/response detail page:

• HTTP status code returned to the client.
• Upstream error code (when applicable).
• Latency, request IP, user-agent.
• Filtering by status helps spot patterns (e.g. all 422s on a specific model).

Reporting an incident

If you see persistent 5xx for a model that should work, email support@kunavo.com with:

• The model slug and a sample request body (redact secrets).
• The time window when failures occurred.
• The error code + message from the response.
• If possible, a usage-log link from /app/usage/[id].

One-business-day response time, faster for urgent revenue-impacting issues.

Where to go next

• How billing affects 402 / quota errors
• API key management