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 ile replacement bilgisini döner:

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

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_balance	Kredi bakiyesi yetersiz	Dashboard > Faturalandırma’dan top-up yap
403	forbidden	Model bu hesap için kullanılamaz	Model erişimini kontrol et
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ı	error.details.replacement_model değerine geç
413	request_too_large	Context window aşıldı	messages içeriğini kısalt
429	rate_limit_exceeded	Rate limit aşıldı	Exponential backoff ile retry et
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

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.