Ana içeriğe atla

​
Genel Bakış

LemonData’nın Agent-First API’si, hata yanıtlarını AI agent’larının anında ayrıştırabileceği ve üzerinde işlem yapabileceği yapılandırılmış ipuçlarıyla zenginleştirir — web araması yok, doküman incelemesi yok, tahmin yürütmek yok. Her hata yanıtı, standart error nesnesi içinde did_you_mean, suggestions, hint, retryable ve retry_after gibi isteğe bağlı alanlar içerir. Bu alanlar geriye dönük uyumludur — bunları kullanmayan istemciler hiçbir fark görmez.

​
Hata İpucu Alanları

Tüm ipucu alanları, error nesnesi içindeki isteğe bağlı uzantılardır:
AlanTürAçıklama
did_you_meanstringEn yakın eşleşen model adı
suggestionsarrayMeta verilerle birlikte önerilen modeller
alternativesarrayŞu anda mevcut olan alternatif modeller
hintstringİnsan/agent tarafından okunabilir sonraki adım rehberliği
retryablebooleanAynı isteğin yeniden denenmesinin başarılı olup olmayacağı
retry_afternumberYeniden denemeden önce beklenecek saniye
balance_usdnumberUSD cinsinden mevcut hesap bakiyesi
estimated_cost_usdnumberBaşarısız olan isteğin tahmini maliyeti

​
Hata Kodu Örnekleri

​
model_not_found (400)

Bir model adı herhangi bir aktif modelle eşleşmediğinde: 
{
  "error": {
    "message": "Model 'gpt5' not found",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-4o",
    "suggestions": [
      {"id": "gpt-4o"},
      {"id": "gpt-4o-mini"},
      {"id": "claude-sonnet-4-5"}
    ],
    "hint": "Did you mean 'gpt-4o'? Use GET /v1/models to list all available models."
  }
}
did_you_mean çözümü şunları kullanır:
  1. Statik takma ad eşlemesi (üretim hata verilerinden)
  2. Normalleştirilmiş dize eşleştirme (tireleri kaldırır, büyük/küçük harfe duyarsızdır)
  3. Düzenleme mesafesi (edit distance) eşleştirme (eşik ≤ 3)

​
insufficient_balance (402)

Hesap bakiyesi tahmini maliyet için çok düşük olduğunda: 
{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-5, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-4o-mini"},
      {"id": "deepseek-chat"}
    ],
    "hint": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-5, but balance is $0.1200. Try a cheaper model, or top up at https://lemondata.cc/dashboard/billing."
  }
}
suggestions, agent’ın geçiş yapabileceği, tahmini maliyetten daha ucuz modelleri içerir.

​
all_channels_failed (503)

Bir model için tüm üst kanal (upstream) bağlantıları kullanılamaz olduğunda: 
{
  "error": {
    "message": "Model claude-opus-4-6 temporarily unavailable",
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-5", "status": "available", "tags": []},
      {"id": "gpt-4o", "status": "available", "tags": []}
    ],
    "hint": "All channels for 'claude-opus-4-6' are temporarily unavailable. Retry in 30s or try an alternative model."
  }
}
retryable, neden no_channels (bu model için yapılandırılmış kanal yok) olduğunda false değerini alır. Yalnızca devre kesici (circuit breaker) tetiklenmesi veya kota tükenmesi gibi geçici hatalar için true değerini alır.

​
rate_limit_exceeded (429)

{
  "error": {
    "message": "Rate limit: 60 rpm exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 60/min for user role."
  }
}
retry_after değeri, gerçek hız sınırı (rate limit) penceresinin sıfırlanma süresinden hesaplanır.

​
context_length_exceeded (400)

Girdi, modelin bağlam penceresini (context window) aştığında (ipuçlarıyla zenginleştirilmiş üst kanal hatası): 
{
  "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-5"}
    ],
    "hint": "Reduce your input or switch to a model with a larger context window."
  }
}

​
Yerel Uç Nokta Başlıkları

Yerel bir uç noktaya (native endpoint) sahip bir modelle (Anthropic veya Gemini) /v1/chat/completions çağrısı yaptığınızda, başarılı yanıt optimizasyon başlıklarını içerir: 
X-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance (no format conversion).
X-LemonData-Native-Endpoint: /v1/messages
Model SağlayıcıÖnerilen Uç NoktaAvantaj
Anthropic (Claude)/v1/messagesFormat dönüştürme yok, genişletilmiş düşünme, prompt önbelleğe alma
Google (Gemini)/v1beta/geminiFormat dönüştürme yok, grounding, güvenlik ayarları
OpenAI—Chat completions zaten yerel formattır
Bu başlıklar hem akışlı (streaming) hem de akışsız yanıtlarda görünür.

​
/v1/models İyileştirmeleri

Her model nesnesinin lemondata uzantısındaki üç yeni alan: 
{
  "id": "gpt-4o",
  "lemondata": {
    "category": "chat",
    "pricing_unit": "per_token",
    "cache_pricing": {
      "cache_read_per_1m": "1.25",
      "cache_write_per_1m": "2.50",
      "platform_cache_discount": 0.9
    }
  }
}
AlanDeğerlerAçıklama
categorychat, image, video, audio, tts, stt, 3d, embedding, rerankModel türü
pricing_unitper_token, per_image, per_second, per_requestModelin nasıl faturalandırıldığı
cache_pricingnesne veya nullÜst kanal prompt önbellek fiyatları + platform semantik önbellek indirimi

​
Kategori Filtreleme

GET /v1/models?category=chat          # Yalnızca sohbet modelleri
GET /v1/models?category=image         # Görüntü oluşturma modelleri
GET /v1/models?tag=coding&category=chat  # Kodlama için optimize edilmiş sohbet modelleri

​
llms.txt

Makine tarafından okunabilir bir API genel bakışı şu adreste mevcuttur: 
GET https://api.lemondata.cc/llms.txt
Şunları içerir:
  • Çalışan bir örnekle birlikte ilk çağrı şablonu
  • Yaygın model adları (kullanım verilerinden dinamik olarak oluşturulur)
  • Tüm 12 API uç noktası
  • Model keşfi için filtre parametreleri
  • Hata yönetimi rehberliği
İlk API çağrısından önce llms.txt dosyasını okuyan AI agent’ları genellikle ilk denemede başarılı olabilir.

​
Agent Kodunda Kullanım

​
Python (OpenAI SDK)

from openai import OpenAI, BadRequestError

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.lemondata.cc/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 {}
        # Otomatik düzeltme için did_you_mean kullanın
        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.lemondata.cc/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;
  }
}

​
Tasarım İlkeleri

Hızlı hata ver, bilgilendirici hata ver

Hatalar, bir agent’ın kendini düzeltmesi için ihtiyaç duyduğu tüm verilerle birlikte anında döner.

Otomatik yönlendirme yok

API asla sessizce farklı bir model yerleştirmez. Kararı agent verir.

Veri odaklı öneriler

Tüm öneriler sabit listelerden değil, üretim verilerinden gelir.

Geriye dönük uyumlu

Tüm ipucu alanları isteğe bağlıdır. Mevcut istemciler hiçbir fark görmez.