Hata Kodları

API hata yanıtları ve çözümleri

Onysoft API, standart HTTP durum kodları ve detaylı hata mesajları döndürür.

HTTP Durum Kodları

Kod Anlam Açıklama
200OKİstek başarıyla tamamlandı
202AcceptedAsenkron görev oluşturuldu (video/görsel/müzik)
400Bad RequestGeçersiz istek formatı veya eksik parametre
401UnauthorizedGeçersiz veya eksik API anahtarı
402Payment RequiredYetersiz bakiye: bakiye, isteğin tahmini tavan maliyetini karşılamıyor (bkz. Bakiye ön kontrolü)
403ForbiddenProje askıda, model engellenmiş veya erişim reddedildi
404Not FoundUç ya da kayıt bulunamadı (yanlış yol, olmayan model ayrıntısı, kullanım kaydı ya da görev kimliği)
413Payload Too Largeİstek boyutu çok büyük (max 10MB — base64 görsel için)
422Unprocessable EntityEksik veya geçersiz parametre (validation_error — örn. model/messages eksik)
429Too Many RequestsRate limit veya token limit aşıldı
500Internal Server ErrorSunucu hatası
502Bad GatewayÜst sağlayıcıdan ya da cihazınızdan geçersiz yanıt (upstream_error, node_error); kısa süre sonra tekrar deneyin
503Service UnavailableHizmet geçici olarak kullanılamıyor: model yoğun (service_unavailable) ya da hazır cihaz yok (node_unavailable, node_busy). Retry-After ve X-Should-Retry başlıklarına uyun

Hata Yanıt Formatı

JSON
{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Yetersiz bakiye. Bakiye yüklemek için: https://api.onysoft.com/dashboard/billing",
    "type": "insufficient_quota",
    "param": null
  }
}

Hata gövdesi OpenAI hata biçimiyle uyumludur: SDK'lar error.message, error.code, error.type ve error.param alanlarını okur. type HTTP koduna göre belirlenir: 401 authentication_error, 402 insufficient_quota, 403 permission_error, 404 not_found_error, 429 rate_limit_error, 5xx server_error, diğerleri invalid_request_error. param hatanın ilgili olduğu alanın adıdır (doğrulama hatalarında ilk hatalı alan; tüm alanlar fields içinde); belirli bir alan yoksa null ya da boştur. Geriye uyum için "success": false ve uca özgü ek alanlar (ör. retry_after, fields, required) korunur. Bu biçim /v1/chat/completions ve diğer uçlar içindir; /v1/responses ile Anthropic uçlarının biçimi aşağıdaki tabloda.

Uca Göre Hata Biçimi

UçHata gövdesi
/v1/chat/completions, diğer uçlarYukarıdaki biçim: {"success": false, "error": {"code", "message", "type", "param"}}
/v1/responsesOpenAI biçimi: {"error": {"message", "type", "param", "code"}}; success alanı yok
/v1/messages, /v1/messages/count_tokens, anthropic-version başlıklı /v1/modelsAnthropic biçimi: {"type": "error", "error": {"type", "message"}}; türler ve eşleme Anthropic Messages API bölümünde

Bakiye Ön Kontrolü (402)

402 yalnız bakiye sıfırlandığında dönmez. Her ücretli istekten önce tahmini tavan maliyet hesaplanır: girdi tahmini + çıktı rezervi; çıktı rezervi max_tokens (ya da max_completion_tokens / Responses'ta max_output_tokens) gönderildiyse odur, gönderilmediyse modelin azami çıktı tokenıdır. Bu tutara %20 güvenlik payı eklenir; bakiyeniz bunun altındaysa istek modele hiç gitmeden 402 insufficient_balance döner. Hata gövdesindeki required ve available alanları gereken ve mevcut tutarı gösterir. Ücret her zaman gerçek kullanımdan kesilir; ön kontrol yalnız yeterlilik denetimidir. Ücretsiz modellerde ön kontrol yapılmaz. Eşik model fiyatına ve güncel kura bağlıdır.

Kod asistanlarında bu eşik yüksek çıkabilir: Codex ve Cursor azami çıktı sınırı göndermez, Claude Code ise 64.000–128.000 çıktı tokenı ister. Bakiyeniz yeterli görünse de 402 alıyorsanız max_tokens / max_output_tokens değerini düşürün; Claude Code'da CLAUDE_CODE_MAX_OUTPUT_TOKENS kullanın.

Hata Metinlerinin Dili

Hata gövdesindeki message alanı Türkçe ya da İngilizce üretilir; code, type, param, HTTP durumu ve ek alanlar (retry_after, fields …) dilden bağımsızdır, değişmez. Öncelik sırası: 1) ?lang=tr / ?lang=en sorgu parametresi. 2) Accept-Language başlığı — gönderilmişse her zaman o kazanır (en yüksek öncelikli dil tr ile başlıyorsa Türkçe, aksi hâlde İngilizce). 3) API anahtarınızın kendi dil ayarı: Panel → API Anahtarları → anahtarın yanındaki ayar düğmesi → “API hata dili”. 4) Hiçbiri yoksa İngilizce. Hâlihazırda açık olan tüm anahtarlar tr ayarıyla başlar (davranış değişmez); bundan sonra açılan anahtarlar en ile açılır. İstisna: kimlik doğrulanmadan önce üretilen hatalar anahtar çözülemediği için her zaman İngilizce döner — 401 invalid_auth, empty_api_key, invalid_api_key_format, invalid_api_key ve 429 too_many_attempts. Bu yanıtlarda Accept-Language: tr göndererek Türkçe alabilirsiniz.

Yaygın Hatalar ve Çözümleri

invalid_api_key

API anahtarınız geçersiz veya deaktif edilmiş. Panelden yeni bir anahtar oluşturun. Authorization başlığı yoksa invalid_auth, anahtar sk-ony- ile başlamıyorsa invalid_api_key_format döner.

insufficient_balance

Bakiyeniz bu istek için yetersiz. Gövdedeki required ve available alanları gereken ve mevcut tutarı gösterir. Bakiye yükleyin ya da max_tokens değerini düşürün (bkz. Bakiye ön kontrolü).

not_found

İstenen uç ya da kayıt bulunamadı: yanlış yol, GET /v1/models/{model_id} ile katalogda olmayan bir model ya da olmayan bir kullanım/işlem kaydı. Sohbet isteğinde katalogda olmayan model ise 400 unsupported_model döner.

rate_limit_exceeded

Dakikalık istek limitini aştınız. Biraz bekleyip tekrar deneyin.

daily_token_limit_exceeded

Bu model için tanımlanan günlük token limitine ulaştınız. Yeni limitinizi yoneticinize (partner) danışın veya günlük sıfırlanmayı bekleyin.

monthly_token_limit_exceeded

Bu model için tanımlanan aylık token limitine ulaştınız. Ayın ilk günü sıfırlanır.

daily_request_limit_exceeded

Bu model için tanımlanan günlük istek sayısı limitine ulaştınız.

model_blocked

Bu model, proje/müşteri için engellenmiş. Erişim için partner veya admin ile iletişime geçin.

free_model_rate_limit

Ücretsiz model kullanım limitini aştınız. 24 saat içinde en fazla 5 istek gönderilebilir.

payload_too_large

İstek boyutu çok büyük. Base64 görsel yüklüyorsanız, görseli küçültün (max 10 MB) veya doğrudan public URL ile gönderin.

generation_failed

Video/görsel/müzik üretimi başarısız oldu. Genellikle üretim servisi tarafında geçici bir sorundur — başka bir model deneyin veya birkaç dakika sonra tekrar deneyin.

unsupported_model

Model kimliği katalogda yok ya da model şu an pasif. Güncel model listesi için GET /v1/models çağırın.

model_not_allowed

403: Anahtarınızda model kilidi tanımlı ve istenen model izinli listede değil (OnyRouter'ın seçtiği model kilitte yoksa da döner). Anthropic uçlarında bu durum 404 not_found_error olarak döner.

free_model_not_eligible

403: Kişisel anahtarlarda ücretsiz modeller (:tr, :free) yalnız doğrulanmış hesaplara açıktır: Google ya da GitHub ile giriş, doğrulanmış e-posta ya da gerçek ödemeyle bakiye yüklemesi gerekir. Proje ve iş ortağı anahtarlarında bu şart aranmaz. Kotaya sayılmaz; X-Should-Retry: false döner.

daily_rate_limit_exceeded

429: Anahtarın günlük istek sınırı (varsayılan 10.000) doldu. Retry-After günün sonuna kadar olan süreyi verir; bu süre 60 saniyeden uzunsa X-Should-Retry: false da döner ve SDK'lar isteği yinelemez.

tr_yogun / tr_concurrency_limit

429: :tr modellerinde aynı anda işlenebilecek istek sınırı doldu (varsayılan 4; kişisel anahtarlarda hesap başına, proje ve iş ortağı anahtarlarında anahtar başına). Fazla istekler kısa bir süre sırada bekler; yer açılmazsa bu hata ve Retry-After döner. Günlük hakkınızdan düşülmez.

tr_model_daily_limit

429: :tr modellerinin günlük istek hakkı doldu (tüm :tr modellerinde ortak). Retry-After hakkın yenileneceği süreyi verir.

unsupported_parameter / unsupported_tool

400: /v1/responses ucunda desteklenmeyen bir alan ya da araç türü gönderildi (ör. previous_response_id, dosya kimliği file_id); code unsupported_parameter ya da unsupported_tool olur ve param alanı ilgili alanı gösterir. /v1/messages ucunda aynı durum Anthropic biçiminde 400 invalid_request_error olarak döner; alan ya da araç adı (ör. file_id, code_execution) hata iletisinde yazar.

upstream_timeout

504: Model yanıtı zaman sınırı içinde tamamlanmadı. Uzun üretimlerde stream: true kullanın; akışta kopma olursa üretilen kısım ücretlendirilir.

Size uygun modeli bulmanıza yardımcı olayım mı?