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 |
|---|---|---|
200 | OK | İstek başarıyla tamamlandı |
202 | Accepted | Asenkron görev oluşturuldu (video/görsel/müzik) |
400 | Bad Request | Geçersiz istek formatı veya eksik parametre |
401 | Unauthorized | Geçersiz veya eksik API anahtarı |
402 | Payment Required | Yetersiz bakiye: bakiye, isteğin tahmini tavan maliyetini karşılamıyor (bkz. Bakiye ön kontrolü) |
403 | Forbidden | Proje askıda, model engellenmiş veya erişim reddedildi |
404 | Not Found | Uç ya da kayıt bulunamadı (yanlış yol, olmayan model ayrıntısı, kullanım kaydı ya da görev kimliği) |
413 | Payload Too Large | İstek boyutu çok büyük (max 10MB — base64 görsel için) |
422 | Unprocessable Entity | Eksik veya geçersiz parametre (validation_error — örn. model/messages eksik) |
429 | Too Many Requests | Rate limit veya token limit aşıldı |
500 | Internal Server Error | Sunucu hatası |
502 | Bad 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 |
503 | Service Unavailable | Hizmet 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ı
{
"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çlar | Yukarıdaki biçim: {"success": false, "error": {"code", "message", "type", "param"}} |
/v1/responses | OpenAI biçimi: {"error": {"message", "type", "param", "code"}}; success alanı yok |
/v1/messages, /v1/messages/count_tokens, anthropic-version başlıklı /v1/models | Anthropic 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
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.
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ü).
İ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.
Dakikalık istek limitini aştınız. Biraz bekleyip tekrar deneyin.
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.
Bu model için tanımlanan aylık token limitine ulaştınız. Ayın ilk günü sıfırlanır.
Bu model için tanımlanan günlük istek sayısı limitine ulaştınız.
Bu model, proje/müşteri için engellenmiş. Erişim için partner veya admin ile iletişime geçin.
Ücretsiz model kullanım limitini aştınız. 24 saat içinde en fazla 5 istek gönderilebilir.
İ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.
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.
Model kimliği katalogda yok ya da model şu an pasif. Güncel model listesi için GET /v1/models çağırın.
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.
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.
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.
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.
429: :tr modellerinin günlük istek hakkı doldu (tüm :tr modellerinde ortak). Retry-After hakkın yenileneceği süreyi verir.
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.
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.