Errors & Status Codes

The Tolka Edge error envelope, every error code, and how to handle AI Rig timeouts and limits.

Tolka Edge mirrors OpenAI's error envelope and adds a tolka_details object so your applications can make precise, automated decisions.

Error envelope

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

Parameter	Type	Description
`message`	string	Human-readable explanation.
`type`	string	Broad error category, e.g. payment_required, gateway_timeout.
`code`	string	Stable machine-readable code — branch your retry logic on this.
`param`	string \| null	The offending field, when applicable.
`tolka_details`	object	Tolka-specific context such as wallet balances or limits.

Status codes

Status	`code`	Meaning	Retryable
`400`	`validation_error`	Malformed request body or missing model.	No
`401`	`auth_error`	Missing or invalid API key.	No
`402`	`insufficient_balance`	Wallet can't cover the request.	After top-up
`403`	`upi_verification_required`	Account not UPI-verified.	After verification
`502`	`proxy_error`	Gateway failed to connect to the Rig.	Yes
`504`	`node_boot_timeout`	The background boot of the AI Rig timed out.	Yes, after 30s

Handling errors in code

from openai import OpenAI, APIStatusError
import os
 
client = OpenAI(base_url="https://api.tolkaedge.com/v1", api_key=os.environ.get("TOLKA_API_KEY"))
 
try:
    resp = client.chat.completions.create(
        model="Qwen/Qwen3-14B",
        messages=[{"role": "user", "content": "Hi"}],
    )
except APIStatusError as e:
    # 402 Payment Required
    if e.status_code == 402:
        print("Please top up your wallet!")
    # 504 Node Boot Timeout
    elif e.status_code == 504:
        print("Rig is taking too long to boot. Please retry.")
    else:
        print(f"Error {e.status_code}: {e.response.json()}")

import OpenAI, { APIError } from "openai";
 
const client = new OpenAI({ baseURL: "https://api.tolkaedge.com/v1", apiKey: process.env.TOLKA_API_KEY });
 
try {
  await client.chat.completions.create({
    model: "Qwen/Qwen3-14B",
    messages: [{ role: "user", content: "Hi" }],
  });
} catch (error) {
  if (error instanceof APIError) {
    if (error.status === 402) {
      console.error("Top up required:", error.error);
    } else if (error.status === 504) {
      console.error("Rig boot timeout. Please wait and retry.");
    } else {
      console.error(`Request failed with status ${error.status}`);
    }
  }
}