Platform

Errors

Predictable error shapes and codes across the API.

Every failed request returns a non-2xx HTTP status and a JSON body describing the failure. The API uses two error shapes, chosen by the endpoint family: the native Krallo endpoints wrap errors in the same { … , "meta": { "request_id" } } envelope they use for success, while the OpenAI-compatible endpoints emit the exact error shape the OpenAI SDKs and coding agents expect. Both are stable contracts — the machine-readable slug never changes for a given failure.

Two error shapes

Native error shape

All native Krallo endpoints — /ping, /me, /guilds, /usage, /personas, /memories, and /webhooks/deliveries — return errors as an error object carrying a stable code and a human-readable message, alongside a meta block with the request’s correlation id. Program against error.code; treat message as display text that may change.

{
  "error": {
    "code": "insufficient_scope",
    "message": "Missing required scope.",
    "required_scope": "ai:invoke"
  },
  "meta": {
    "request_id": "9f2c1ab4-e7d8-4b3a-a1c5-6e0f2d8b7c94"
  }
}

Some codes attach extra fields inside the error object to help you recover programmatically — for example required_scope on insufficient_scope, and required_units / balance on insufficient_credits. Unknown fields may be added over time, so parse defensively.

OpenAI-compatible error shape

The OpenAI-compatible endpoints — chat completions (POST /api/v1/chat/completions), GET /api/v1/models, and image generation (POST /api/v1/ai/imagine) — return the OpenAI error shape instead, so a stock OpenAI client, Aider, Continue, nanocoder, or opencode parses failures without special handling. The machine-readable slug lives in type, the message in message, and there is no meta block.

{
  "error": {
    "message": "Unknown model 'gpt-5'. Valid models: krallo-chat, krallo-code, krallo-fast, krallo-reasoning.",
    "type": "model_not_found"
  }
}

HTTP status codes

The status code tells you the class of failure; the body’s code/type tells you the specific reason. A 404 is also what you get for any request while the developer API is disabled, so an integration that suddenly 404s everywhere should assume the surface is dark rather than that a single route was removed.

Error codes

The full set of stable slugs. “Shape” indicates whether the slug appears as error.code (native), error.type (OpenAI-compatible), or both. Match on the slug, not the message.

Insufficient credits (402)

A 402 means the app has exhausted its free daily quota and the owner’s prepaid wallet cannot cover the call. The body always includes required_units (the weighted credit units this call needed) and balance (the wallet balance at the time of the failure), so you can surface a precise top-up prompt. The shape follows the endpoint family.

Native endpoints and image generation return the native shape. required_units is the flat per-call price for native endpoints (default 1) or the fixed image cost for /ai/imagine (default 10):

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credit balance for this request.",
    "required_units": 10,
    "balance": 3
  },
  "meta": {
    "request_id": "9f2c1ab4-e7d8-4b3a-a1c5-6e0f2d8b7c94"
  }
}

Chat completions returns the OpenAI shape. Because chat is token-metered, the reservation is pre-authorised before inference runs, so required_units is the pre-authorisation reserve (default 250) rather than a per-call flat price — the call 402s before the model runs:

{
  "error": {
    "message": "Insufficient credit balance for this request.",
    "type": "insufficient_credits",
    "required_units": 250,
    "balance": 3
  }
}

Handling errors

Branch on the HTTP status first, then on the slug. A robust client should:

• Never parse the message for control flow — match error.code (native) or error.type (OpenAI). Messages are display text and may be reworded.
• Not retry 4xx other than 429 — they are deterministic (fix the request, scope, or credits). 401/403 won’t succeed on retry with the same key.
• Retry 429, 500, 502, and 504 with exponential backoff and jitter. For 429, wait at least the Retry-After seconds.
• Capture meta.request_id from native responses. When you contact support about a failure, quote it — it lets us find the exact request in the access log. It may be an empty string if the request was rejected before correlation was assigned; the OpenAI-compatible endpoints do not return one.

Node.js

const res = await fetch("https://exe.krallo.com/api/v1/me", {
  headers: { Authorization: `Bearer ${process.env.KRALLO_API_KEY}` },
});

if (!res.ok) {
  const body = await res.json().catch(() => ({}));
  // Native endpoints: error.code + meta.request_id.
  // OpenAI-compatible endpoints (/chat/completions, /models, /ai/imagine): error.type.
  const slug = body?.error?.code ?? body?.error?.type ?? "unknown";
  const requestId = body?.meta?.request_id;

  if (res.status === 402) {
    // Out of credits — surface a top-up. required_units / balance are on error.
    throw new Error(`Insufficient credits (needed ${body.error.required_units}, balance ${body.error.balance})`);
  }
  if (res.status === 429 || res.status >= 500) {
    // Transient — retry with backoff, honouring Retry-After on 429.
    throw new RetryableError(slug, res.headers.get("retry-after"));
  }
  throw new Error(`${res.status} ${slug}${requestId ? ` (request_id=${requestId})` : ""}`);
}

See also

• Authentication — token lifecycle behind the 401 codes.
• Scopes — the grants behind insufficient_scope and invalid_scope.
• Rate limits — the 429 contract and rate-limit headers.
• Billing & quotas — quota resets and the wallet behind insufficient_credits.