✨ Agent-First API

Overview

AI Sonar’s Agent-First API enriches error responses with structured hints that AI agents can parse and act on immediately — no web searches, no doc lookups, no guesswork. OpenAI-compatible Chat Completions and Responses gateway errors may include optional fields such as did_you_mean, suggestions, hint, retryable, and retry_after inside the error object. Anthropic Messages and Gemini endpoints keep their native error shapes and do not promise these extensions.

Error Hint Fields

For OpenAI-compatible gateway errors, all hint fields are optional extensions inside the error object:

Field	Type	Description
`did_you_mean`	`string`	Closest matching model name
`suggestions`	`array`	Recommended models with metadata
`alternatives`	`array`	Currently available alternative models
`hint`	`string`	Human/agent-readable next-step guidance
`retryable`	`boolean`	Whether retrying the same request may succeed
`retry_after`	`number`	Seconds to wait before retrying
`balance_usd`	`number`	Current account balance in USD
`estimated_cost_usd`	`number`	Estimated cost of the failed request

Error Code Examples

model_not_found (400)

When a model name doesn’t match any active model:

{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.4",
    "suggestions": [
      {"id": "gpt-5.4"},
      {"id": "gpt-5-mini"},
      {"id": "claude-sonnet-4-6"}
    ],
    "hint": "Did you mean 'gpt-5.4'? Use GET https://api.aisonar.dev/v1/models to list all available models."
  }
}

The did_you_mean resolution uses:

Static alias mapping (from production error data)
Normalized string matching (strips hyphens, case-insensitive)
Edit distance matching (threshold ≤ 3)

Public routes do not expose separate error codes for hidden, deferred, or non-public models. Treat unavailable public models the same way as a miss: inspect did_you_mean, suggestions, and hint, then retry with a supported public model.

insufficient_balance (402)

When account balance is too low for the estimated cost:

{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5-mini"},
      {"id": "deepseek-v3-2"}
    ],
    "hint": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200. Try a cheaper model or contact support to add balance."
  }
}

suggestions contains models cheaper than the estimated cost that the agent can switch to.

Temporary service errors (5xx)

When a model is temporarily unavailable, retry only when the response sets retryable to true:

{
  "error": {
    "message": "Model claude-opus-4-6 temporarily unavailable",
    "type": "server_error",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-6", "status": "available", "tags": []},
      {"id": "gpt-5-mini", "status": "available", "tags": []}
    ],
    "hint": "Retry in 30s or try an alternative model."
  }
}

When retryable is false, follow hint or switch to a model listed in alternatives.

rate_limit_exceeded (429)

{
  "error": {
    "message": "Rate limit: 1000 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
  }
}

The retry_after value is calculated from the actual rate limit window reset time.

OpenAI-compatible endpoints use the standard error envelope shown above. Anthropic-compatible and Gemini-compatible endpoints use their native response formats.

context_length_exceeded (400)

When input exceeds the model’s context window (with corrective hints):

{
  "error": {
    "message": "This model's maximum context length is 128000 tokens...",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "retryable": false,
    "suggestions": [
      {"id": "gemini-2.5-pro"},
      {"id": "claude-sonnet-4-6"}
    ],
    "hint": "Reduce your input or switch to a model with a larger context window."
  }
}

Native Endpoint Discovery

Do not infer native protocol availability from a model or provider name, or from Chat response headers. Before choosing a native endpoint, read GET /v1/models/{model} and use only a format in aisonar.accepted_request_formats. Native requests use only the advertised protocol; temporary service availability is still decided at request time.

Request format	Endpoint
Chat Completions	`/v1/chat/completions`
Responses	`/v1/responses`
Messages	`/v1/messages`
Gemini	`/v1beta/models/{model}:generateContent`

An advertised request format controls endpoint availability; support for individual fields and tools remains service-specific.

/v1/models Enhancements

/v1/models now carries non-chat recommendation metadata that agents can use before they call image, video, music, 3D, TTS, STT, embedding, rerank, or translation endpoints.

{
  "id": "gemini-2.5-flash-image",
  "aisonar": {
    "category": "image",
    "pricing_unit": "per_request",
    "agent_preferences": {
      "image": {
        "preferred_rank": 1,
        "success_rate_24h": 0.98,
        "sample_count_24h": 423,
        "status": "ready",
        "updated_at": "2026-03-28T12:00:00.000Z",
        "basis": {
          "source": "recent_activity_24h"
        }
      }
    }
  }
}

Field	Values	Description
`category`	`chat`, `image`, `video`, `audio`, `tts`, `stt`, `3d`, `embedding`, `rerank`	Model type
`pricing_unit`	`per_token`, `per_image`, `per_second`, `per_request`	How the model is billed
`cache_pricing`	object or `null`	Model-specific prompt cache prices.
`agent_preferences.<scene>`	object	Non-chat recommendation snapshot for that scene, only on `GET /v1/models?recommended_for=<scene>`

When recommended_for is present, agent_preferences is derived from a cached 24-hour success-rate snapshot:

Window: 24 hours
Snapshot cache: stale-while-revalidate
status = "ready" means the model has enough recent samples to participate in ranking
status = "insufficient_samples" means the model stays visible but is not ranked ahead of scored models

Category Filtering

GET https://api.aisonar.dev/v1/models?category=chat          # Chat models only
GET https://api.aisonar.dev/v1/models?category=image         # Image generation models
GET https://api.aisonar.dev/v1/models?tag=coding&category=chat  # Coding-optimized chat models

Recommendation Discovery

For non-chat workflows, agents should fetch the current recommended shortlist first:

GET https://api.aisonar.dev/v1/models?recommended_for=image
GET https://api.aisonar.dev/v1/models?recommended_for=translation
GET https://api.aisonar.dev/v1/models?category=tts&recommended_for=tts

Valid recommended_for values are:

image
video
music
3d
tts
stt
embedding
rerank
translation

If both category and recommended_for are present, they must match exactly. Recommended agent flow:

GET /v1/models?recommended_for=<scene>
Pick the first agent_preferences.<scene>.status == "ready" model
Call the endpoint explicitly with model=<selected>
On transient errors only, retry with the next ready model

llms.txt

A machine-readable API overview is available at:

GET https://api.aisonar.dev/llms.txt

It includes:

First-call template with a working example
Common model names (dynamically generated from usage data)
All 12 API endpoints
Filter parameters for model discovery
Error handling guidance

AI agents that read llms.txt before their first API call can typically succeed on the first attempt.

Usage in Agent Code

Python (OpenAI SDK)

from openai import OpenAI, BadRequestError

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.aisonar.dev/v1"
)

def smart_chat(messages, model="gpt-4o"):
    try:
        return client.chat.completions.create(
            model=model, messages=messages
        )
    except BadRequestError as e:
        error = e.body.get("error", {}) if isinstance(e.body, dict) else {}
        # Use did_you_mean for auto-correction
        if error.get("code") == "model_not_found" and error.get("did_you_mean"):
            return client.chat.completions.create(
                model=error["did_you_mean"], messages=messages
            )
        raise

JavaScript (OpenAI SDK)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-key',
  baseURL: 'https://api.aisonar.dev/v1'
});

async function smartChat(messages, model = 'gpt-4o') {
  try {
    return await client.chat.completions.create({ model, messages });
  } catch (error) {
    const err = error?.error;
    if (err?.code === 'model_not_found' && err?.did_you_mean) {
      return client.chat.completions.create({
        model: err.did_you_mean, messages
      });
    }
    throw error;
  }
}

Design Principles

Fail fast, fail informatively

Errors return immediately with all the data an agent needs to self-correct.

No auto-routing

The API never silently substitutes a different model. The agent decides.

Data-driven suggestions

All recommendations come from production data, not hardcoded lists.

Backward compatible

All hint fields are optional. Existing clients see no difference.

Getting Started

Core Guides

Media Guides

✨ Agent-First API

Overview

Error Hint Fields

Error Code Examples

model_not_found (400)

insufficient_balance (402)

Temporary service errors (5xx)

rate_limit_exceeded (429)

context_length_exceeded (400)

Native Endpoint Discovery

/v1/models Enhancements

Category Filtering

Recommendation Discovery

llms.txt

Usage in Agent Code

Python (OpenAI SDK)

JavaScript (OpenAI SDK)

Design Principles

Fail fast, fail informatively

No auto-routing

Data-driven suggestions

Backward compatible

​Overview

​Error Hint Fields

​Error Code Examples

​model_not_found (400)

​insufficient_balance (402)

​Temporary service errors (5xx)

​rate_limit_exceeded (429)

​context_length_exceeded (400)

​Native Endpoint Discovery

​/v1/models Enhancements

​Category Filtering

​Recommendation Discovery

​llms.txt

​Usage in Agent Code

​Python (OpenAI SDK)

​JavaScript (OpenAI SDK)

​Design Principles

Fail fast, fail informatively

No auto-routing

Data-driven suggestions

Backward compatible

Overview

Error Hint Fields

Error Code Examples

model_not_found (400)

insufficient_balance (402)

Temporary service errors (5xx)

rate_limit_exceeded (429)

context_length_exceeded (400)

Native Endpoint Discovery

/v1/models Enhancements

Category Filtering

Recommendation Discovery

llms.txt

Usage in Agent Code

Python (OpenAI SDK)

JavaScript (OpenAI SDK)

Design Principles