API hataları

Bu sayfada, tüm Interactions API hata kodları için bir referans sunulmakta, hata yanıtı biçimi açıklanmakta ve API'nin farklı istek türleri için hataları nasıl ilettiği anlatılmaktadır.

Standart API hata kodları

İstek düzeyindeki bu genel hata kodları, standart HTTP durum kodlarına karşılık gelir. Hataları programatik olarak işlemek için uygulama mantığınızda code alanını kullanın.

Kod HTTP Durumu Açıklama Önerilen işlem
invalid_request 400 Hatalı İstek İstek yükü hatalı biçimlendirilmiş veya geçersiz parametreler içeriyor. İstek söz diziminizi ve parametrelerinizi API referansına göre kontrol edin.
failed_precondition 400 Hatalı İstek Ön koşul karşılanmadığı için (ör. devre dışı bırakılmış faturalandırma) istek işlenemiyor. Proje faturalandırma durumunu veya hesap ön koşullarını doğrulayın.
out_of_range 416 İstenen Aralık Karşılanamıyor İstek parametresi geçerli aralığın dışında. Parametre değerlerini ve sınırlarını kontrol edin.
parameter_unknown 400 Hatalı İstek İstek, bilinmeyen bir parametre içeriyor. Tanınmayan parametreyi kaldırıp tekrar deneyin.
authentication 401 Yetkilendirilmedi API anahtarı eksik, geçersiz veya süresi dolmuş. API anahtarınızı doğrulayın.
payment_required 402 Ödeme Gerekli Ön ödeme kredi bakiyeniz tükendi. Faturalandırma hesabınıza kredi ekleyin veya otomatik para yükleme özelliğini etkinleştirin. Yeniden denemeyin: Kredi eklenene kadar istek başarılı olmaz.
permission_denied 403 Yasak API anahtarınızın bu kaynak için izni yok veya projenizin API erişimi kısıtlanmış. API anahtarı izinlerinizi, proje katmanı uygunluğunuzu ve faturalandırma durumunuzu kontrol edin. Projenin kısıtlanması veya kullanılamamasıyla ilgili sorunları giderme başlıklı makaleyi inceleyin.
not_found 404 Bulunamadı İstenen kaynak bulunamadı. Kaynak yolunu ve parametreleri doğrulayın.
model_not_found 404 Bulunamadı Belirtilen model bulunamadı. Model adını doğrulayın veya farklı bir modele geçin.
already_exists 409 Çakışma Oluşturmayı denediğiniz varlık zaten mevcut. Yeniden oluşturmadan önce kaynağın mevcut olup olmadığını kontrol edin.
aborted 409 Çakışma İşlem, çakışma veya eşzamanlılık kontrolü hatası nedeniyle iptal edildi. İsteği daha yüksek bir uygulama düzeyinde yeniden deneyin.
rate_limit_exceeded 429 Too Many Requests (Çok Fazla İstek) Dakika veya saniye başına istek ya da jeton sınırını aştınız. Bekleyin ve eksponansiyel geri yüklemeyle yeniden deneyin.
quota_exceeded 429 Too Many Requests (Çok Fazla İstek Var) Günlük kotanızı aştınız. Kota sıfırlanana kadar bekleyin veya kota artışı isteyin.
too_many_requests 429 Too Many Requests (Çok Fazla İstek Var) Kısa süre içinde çok fazla istek gönderdiniz. Bekleyin ve eksponansiyel geri yüklemeyle yeniden deneyin.
cancelled 499 İstemci İsteği Kapattı İstemci, isteği tamamlanmadan önce iptal etti. Herhangi bir işlem yapmanız gerekmez. Bu genellikle istemcinin bağlantısının kesildiği anlamına gelir.
api_error 500 Dahili Sunucu Hatası Sunucuda beklenmeyen bir hata oluştu. İsteği yeniden deneyin. Sorun devam ederse destek ekibiyle iletişime geçin.
unimplemented 501 Uygulanmadı İşlem veya özellik uygulanmıyor ya da desteklenmiyor. API özelliklerini kontrol edin veya desteklenen bir özelliğe geçin.
service_unavailable 503 Hizmet Kullanılamıyor Hizmet geçici olarak aşırı yüklü veya çalışmıyor. Bekleyin ve eksponansiyel geri yüklemeyle tekrar deneyin.
deadline_exceeded 504 Ağ Geçidi Zaman Aşımı İstek, son tarihe kadar tamamlanmadı. Sunucu varsayılanını kullanmak için istemci son tarih ayarını kaldırın veya artırın.

Oluşturma engellendi kodları

Bu hata kodları, modelin çıkışının politika, güvenlik veya içerik kısıtlamaları nedeniyle engellendiğini gösterir. Bu kodlardan birini aldığınızda girişinizi değiştirip tekrar deneyin.

Kod Açıklama
safety Güvenlik ihlalleri (zararlı içerik) nedeniyle istek engellendi.
recitation Telif hakkı veya okuma kısıtlamaları nedeniyle istek engellendi.
language Desteklenmeyen bir dil nedeniyle istek engellendi.
prohibited_content Yasaklanmış içerik yönergeleri nedeniyle istek engellendi.
spii Hassas kişisel veri kısıtlamaları isteği engelledi.
blocklist Engellenenler listesindeki yasaklı terimler isteği engelledi.
image_safety Güvenlik ihlalleri nedeniyle görüntü üretme engellendi.
image_prohibited_content Yasaklanmış içerik yönergeleri nedeniyle görüntü üretme engellendi.
image_recitation Telif hakkı veya ezberden okuma kısıtlamaları nedeniyle görüntü üretilemedi.
image_other Belirtilmeyen nedenlerle görüntü üretme engellendi.
content_blocked Belirtilmeyen bir politika nedeni, isteği engelledi.

Oluşturma hatası kodları

Bu hata kodları, modelin oluşturduğu çıkışla ilgili yapısal bir sorunu (ör. hatalı biçimlendirilmiş bir işlev çağrısı veya bildirilmemiş bir araç çağrısı) gösterir.

Kod Açıklama
malformed_function_call Model, ayrıştırılamayan bir işlev çağrısı üretti.
malformed_tool_call Model, ayrıştırılamayan bir araç çağrısı üretti.
unexpected_tool_call Model, istekte belirtilmeyen bir aracı çağırdı.
no_image Model, resim üretemedi.
too_many_tool_calls Model, izin verilenden daha fazla araç çağrısı oluşturdu.
missing_thought_signature Yanıtta gerekli bir düşünce imzası eksik.

Hata yanıtı biçimi

Interactions API'den gelen tüm hatalar, code ve message içeren bir error nesnesi döndürür. Örneğin, desteklenmeyen bir araç türü iletildiğinde şu yanıt döndürülür:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
Alan Tür Açıklama
code dize snake_case içinde makine tarafından okunabilir bir hata kodu.
message dize Sorunun ne olduğuna dair, kullanıcılar tarafından okunabilir açıklama.

Hatalar nasıl bildirilir?

API, standart bir HTTP isteği mi yoksa akış (SSE) isteği mi yaptığınıza bağlı olarak hataları farklı şekilde iletir.

Standart HTTP istekleri

Standart (akış dışı) istekler için API, HTTP yanıt durum kodunu (400 Bad Request, 401 Unauthorized veya 429 Too Many Requests gibi) ayarlar ve JSON yanıt gövdesinde bir error nesnesi döndürür:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

Akış (SSE) istekleri

Akış istekleri (stream: true) için API, event_type değeri "error" olarak ayarlanmış şekilde Sunucu Tarafından Gönderilen Etkinlikler (SSE) akışı üzerinden hata etkinlikleri gönderir. error alanı aynı code ve message yapısını içerir:

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

SSE etkinlik şemasının tamamı için Interactions API referansına bakın.

Sırada ne var?