Error Handling

Build resilient integrations against Tolka's structured error envelope, with per-code handling strategies.

Tolka returns a structured, OpenAI-compatible error envelope so your code can branch on stable machine-readable codes.

The envelope

{
  "error": {
    "message": "Insufficient balance to route request.",
    "type": "payment_required",
    "code": "insufficient_balance",
    "param": "wallet",
    "tolka_details": { "balance_paise": 340, "required_paise_for_model": 400 }
  }
}

Always branch on error.code — messages may be reworded, codes are stable.

Per-code strategy

`code`	Status	Strategy
`validation_error`	400	Fix the request. Not retryable.
`auth_error`	401	Check the key. Not retryable.
`insufficient_balance`	402	Prompt a top-up; halt until funded.
`upi_verification_required`	403	Route the user to verification.
`model_not_found`	404	Correct the slug; list `/v1/models`.
`request_timeout`	408	The dedicated vLLM queue is full. Back off and retry.
`internal_error`	500	Retry with backoff; alert if persistent.

A robust handler

from openai import APIStatusError
 
def call_with_handling(**kwargs):
    try:
        return client.chat.completions.create(**kwargs)
    except APIStatusError as e:
        err = e.response.json().get("error", {})
        code = err.get("code")
        if code == "insufficient_balance":
            raise NeedsTopUp(err["tolka_details"])
        if code in ("request_timeout", "internal_error"):
            raise Retryable(code)
        raise  # validation/auth: surface immediately

import { APIError } from "openai";
 
async function callWithHandling(args: any) {
  try {
    return await client.chat.completions.create(args);
  } catch (e) {
    if (e instanceof APIError) {
      if (e.code === "insufficient_balance") throw new NeedsTopUp();
      if (e.code === "request_timeout" || e.code === "internal_error") throw new Retryable();
    }
    throw e;
  }
}

Streaming errors

A stream that fails mid-flight ends with a final frame:

data: {"error": "stream_interrupted"}

Interrupted streams are billed for tokens delivered and logged as partial. Preserve the partial output and, if needed, retry only the remainder.

🔁

Retry strategy

Exponential backoff, jitter and idempotency.