Hatalar

Tüm hata yanıtları tutarlı formatta döner:

{
  "error": {
    "message": "Invalid API key",
    "type": "auth_error"
  }
}

Bazı hatalar (özellikle yanlış endpoint × model kombinasyonu) opsiyonel bir details nesnesi içerir. Mevcut entegrasyonlar error.message ve error.type üzerinden çalışmaya devam eder; yeni details nesnesi geriye uyumlu eklenmiştir.

{
  "error": {
    "message": "The model \"google/gemini-3.1-flash-image\" does not support /v1/images/edits. Use /v1/images/generations instead. For image-to-image, try-on or image merging, send reference images via the 'file_ids' field (after uploading them through /v1/files), or via 'image_urls' for hosted URLs.",
    "type": "unsupported_operation",
    "details": {
      "param": "model",
      "model": "google/gemini-3.1-flash-image",
      "attempted_endpoint": "/v1/images/edits",
      "supported_endpoints": ["/v1/images/generations"],
      "suggested_endpoint": "/v1/images/generations",
      "hint": "For image-to-image, try-on or image merging, send reference images via the 'file_ids' field (after uploading them through /v1/files), or via 'image_urls' for hosted URLs.",
      "docs_url": "https://llmtr.com/docs/gateway/image-generation/"
    }
  }
}

details alanları:

Alan	Açıklama
param	Hatalı request alanı (genellikle model)
model	Çağrıdaki canonical model ID'si
attempted_endpoint	İsteğin yapıldığı endpoint
supported_endpoints	Bu modelin gerçekten desteklediği endpoint listesi
suggested_endpoint	Çağrıyı düzeltmek için tek tıkta gidilecek endpoint
hint	Provider/model bazlı kısa yönlendirme (örn. file_ids kullan)
docs_url	Konuyla ilgili kılavuz

Emekliye ayrılan model kimlikleri HTTP 410 döner. Bazı emekliliklerde replacement_model ve gerekiyorsa replacement_endpoint alanları bulunur:

{
  "error": {
    "message": "Model \"openai/o3-pro-2025-06-10\" was retired on 2026-12-10. Use \"openai/gpt-5.5-pro\" on /v1/responses instead.",
    "type": "model_retired",
    "details": {
      "model": "openai/o3-pro-2025-06-10",
      "replacement_model": "openai/gpt-5.5-pro",
      "retirement_date": "2026-12-10",
      "replacement_endpoint": "/v1/responses"
    }
  }
}

MiMo V2 legacy kimliklerinde replacement aynı chat endpoint'inde kullanılır:

{
  "error": {
    "message": "Model \"mimo/mimo-v2-flash\" was retired on 2026-06-30. Use \"mimo/mimo-v2.6-flash\" instead.",
    "type": "model_retired",
    "details": {
      "model": "mimo/mimo-v2-flash",
      "replacement_model": "mimo/mimo-v2.6-flash",
      "retirement_date": "2026-06-30"
    }
  }
}

Replacement verilmeyen emekliliklerde LLMTR otomatik yönlendirme yapmaz:

{
  "error": {
    "message": "Model \"google/imagen-4.0-fast-generate-001\" was retired on 2026-08-17. This identifier is no longer accepted by LLMTR. Choose an active Google image model explicitly.",
    "type": "model_retired",
    "details": {
      "model": "google/imagen-4.0-fast-generate-001",
      "retirement_date": "2026-08-17",
      "status": "retired"
    }
  }
}

Hata türleri

HTTP	type	Neden	Ne yapmalı?
400	invalid_request_error	Geçersiz JSON, eksik alan, bilinmeyen parametre	İsteği düzelt, schema'ya bak
401	auth_error	Geçersiz/revoke edilmiş anahtar	Dashboard'dan yeni anahtar üret
402	insufficient_credits	Kredi bakiyesi bu isteğin rezervasyonuna yetmiyor	Dashboard > Faturalandırma'dan top-up yap veya daha düşük bir max_tokens gönder
402	insufficient_credits	details.reason: "top_up_required": bu ücretsiz model yalnızca en az bir kez bakiye yüklemiş hesaplara açık	Dashboard > Faturalandırma'dan bir kez top-up yap (en az 5 $), bir dakika sonra tekrar dene; model bakiyeden düşmez
402	insufficient_credits	details.reason: "account_verification_required": otomatik kullanım koruması bu ücretsiz model için hesabın doğrulanmasını istiyor	Dashboard > Faturalandırma'dan bir kez top-up yap (en az 5 $), bir dakika sonra tekrar dene; model bakiyeden düşmez
402	insufficient_credits	details.reason: "trial_request_too_large": istek, bu ücretsiz modeldeki deneme hakkının kalanından büyük	Daha kısa bir istek gönder ya da Dashboard > Faturalandırma'dan bir kez top-up yap (en az 5 $); model bakiyeden düşmez
402	insufficient_quota	details.reason: "free_spend_user_cap_reached": bu ücretsiz model için hesabına ayrılan kullanım bu dönem için doldu	Başka bir model kullan; bu hak dönem bitene kadar yenilenmez
402	spending_limit_exceeded	API anahtarının harcama limiti doldu veya bu isteğe yetmiyor	Anahtarın limitini yükselt veya daha düşük bir max_tokens gönder
403	forbidden	Model bu hesap için kullanılamaz	Model erişimini kontrol et
403	model_not_allowed	Anahtarın model kısıtı bu modeli kapsamıyor	Kısıtı düzenle ya da kapsamdaki bir modeli çağır
403	permission_error	Anahtar bu istek için yetkili değil; örneğin anahtarın IP kısıtı bu ağı kapsamıyor	error.message'ı oku; IP kısıtıysa çıkış adresini anahtarın IP listesine ekle
403	account_banned	Hesap askıya alındı	Anahtar yenilemek çözmez; info@llmtr.com ile iletişime geçin
403	automated_gateway_not_allowed	İstek, API anahtarlarını otomatik doğrulayan bir araçtan geliyor	Bu araçlar desteklenmez; anahtarı kendi uygulamanızdan gerçek bir modelle kullanın
404	model_not_found	model alanı bilinmeyen	Canonical ID'yi kontrol et (provider/model)
410	model_retired	Model kimliği kullanımdan kaldırıldı	replacement_model varsa ona geç; yoksa katalogdan aktif bir modeli açıkça seç
413	request_too_large	Context window aşıldı	messages içeriğini kısalt
429	rate_limit_error	Rate limit aşıldı	Exponential backoff ile retry et
429	rate_limit_error (details.reason: "free_access_paused")	Ücretsiz modeller geçici olarak durduruldu: details.scope api_key ise yalnızca bu anahtar için, account ise hesabın tüm anahtarları için. Ücretli modeller çalışır	Retry-After süresi sonunda tekrar dene veya ücretli bir model kullan; hata olduğunu düşünüyorsan info@llmtr.com
429	rate_limit_error (details.reason: "unpaid_account_limit")	Bakiye yüklememiş hesaptan kısa sürede çok fazla istek geldi; hesabın tüm anahtarları birlikte sayılır	Retry-After süresi sonunda tekrar dene; hesaba bakiye yüklediğinde sınır kısa süre içinde kalkar
500	internal_error	Gateway iç hatası	Kısa süre sonra tekrar dene
502	provider_error	Sağlayıcı tarafında hata	Geçici olabilir, retry dene
503	provider_unavailable	Sağlayıcı erişilemez	Bir süre sonra tekrar dene
504	timeout	İstek zaman aşımına uğradı	Daha kısa çıktı iste veya streaming dene

Askıya alınmış hesap

Bir hesap yönetici tarafından askıya alındığında o hesaba ait tüm API anahtarları 403 döner:

{
  "error": {
    "message": "This account has been suspended. Contact info@llmtr.com if you believe this is a mistake.",
    "type": "account_banned"
  }
}

Bu hata 401 auth_error ile karıştırılmamalıdır. 401 anahtarın geçersiz olduğunu söyler ve yeni anahtar üretmek çözer; account_banned ise anahtarın geçerli olduğunu ama hesabın yetkili olmadığını söyler — yeni anahtar üretmek hiçbir şeyi değiştirmez.

Retry edilebilir bir hata değildir: tekrar denemek aynı yanıtı döndürür. İstemci tarafında bu tipi kalıcı hata olarak işleyin ve backoff döngüsüne sokmayın.

/v1/messages (Anthropic uyumlu) yüzeyinde aynı durum Anthropic'in kendi zarfıyla permission_error tipinde döner.

Retry stratejisi

Retry sadece 429, 500, 502, 503, 504 için.
Backoff: exponential + jitter.
Max retry: 3.

Örnek (Python):

import time, random
from openai import OpenAI, APIStatusError

RETRIABLE = {429, 500, 502, 503, 504}

def call(client, payload, attempt=0):
    try:
        return client.chat.completions.create(**payload)
    except APIStatusError as e:
        if e.status_code in RETRIABLE and attempt < 3:
            time.sleep(2 ** attempt + random.random())
            return call(client, payload, attempt + 1)
        raise

Retry uygularken istemci tarafında timeout, bağlantı kopması ve çift gönderim senaryolarını da hesaba katın.