AI errors

When the AI binding refuses a call, it says why in plain words and tells you what to do. Nothing is spent on a refused call. This page lists every error code, grouped by the kind of fix.

What an error looks like

An error is a JSON body with a stable code, a message you can show, and a how_to_fix sentence.

{
  "type": "error",
  "error": {
    "type": "model_not_allowed",
    "code": "model_not_allowed",
    "message": "This tool is not set up to use \"claude-sonnet-5-5\".",
    "how_to_fix": "Allowed models: claude-haiku-5-5. Add the model to bindings.ai.models in the manifest and deploy again."
  }
}

The same body works for both stock libraries. The OpenAI library reads error.message, error.type and error.code. The Anthropic library reads the top-level type and error.type. A few errors that happen before the AI part of the gateway, such as invalid_token, binding_not_declared and the gateway-wide rate_limited, have only code, message and how_to_fix. Always read code.

Every answer carries these headers:

Catching errors in your code

import { PlatformError } from '@cohostly/sdk'

try {
  const reply = await platform.ai.messages({ model: 'gemini-3.5-flash-lite', messages })
  return reply.text
} catch (e) {
  if (!(e instanceof PlatformError)) throw e
  // e.status, e.code, e.message, e.howToFix, e.requestId
  if (e.code === 'ai_budget_exhausted') return 'The AI budget for this month is used up.'
  if (e.code === 'provider_key_needed') return 'This app needs an AI key. Ask the account owner.'
  return e.message
}

import os
from openai import OpenAI, APIStatusError

client = OpenAI(base_url=os.environ["AI_BASE_URL"], api_key=os.environ["AI_API_KEY"], max_retries=0)

try:
    reply = client.chat.completions.create(
        model="gemini-3.5-flash-lite",
        messages=[{"role": "user", "content": "Hello"}],
    )
except APIStatusError as e:
    print(e.status_code, e.code, e.message)

With the typed call, the network failing gives a PlatformError with status 0 and code network_error. Running outside the platform with no token gives code not_configured. Run locally with cohostly dev -- <command> (develop).

Good to know Stock libraries retry some errors on their own. A refusal such as ai_budget_exhausted will not change by trying again, so consider turning their automatic retries off (max_retries=0 or maxRetries: 0) and deciding yourself. The typed call never retries.

Should I retry?

Setup mistakes

These come from the request or the settings file. Fix them in your code or cohostly.json, and deploy.

Keys

These apply to models paid with your own key. See bring your own key.

Limits and spending

See models and costs for how each cap is worked out.

Something is down for a moment

ai_not_configured (HTTP 503, "AI is not set up on this platform yet") can only appear on a platform that has not connected a model provider. You should not see it on Cohostly.

When it fails after the answer starts

When you ask for a live reply (streaming), the gateway has already answered 200 before the model finishes. If something goes wrong after that, the connection ends. No JSON error is sent after the first words. Treat a stream that stops early as an incomplete answer. See HTTP and streaming.

Related