Yapay Zeka API'lerinde Hata Kodları ve Anlamları

Neden Hata Kodlarını Anlamak Önemli?

Yapay zeka API'leri ile çalışırken beklenmedik hatalarla karşılaşmak her geliştiricinin başına gelir. Hata mesajlarını doğru okumak, sorunun kaynağını hızla belirlemenizi sağlar ve geliştirme sürecinizi yarıda kesen zaman kaybını önler. Özellikle OpenAI uyumlu API'ler kullandığınızda standart hata kodlarına hakim olmak, farklı platformlar arasında geçiş yaparken de işinizi kolaylaştırır. Sen Apicloud (apicloud.com.tr) gibi platformlarda da benzer hata yapılarıyla karşılaşabilirsiniz; dolayısıyla bu bilginin genel geçer olduğunu söyleyebiliriz.

Yaygın HTTP Durum Kodları ve Anlamları

API istekleri sırasında dönen HTTP kodları, hatanın genel kategorisini anlamanızı sağlayan ilk ipucudur. İşte en sık karşılaştığınız kodlar:

• 400 Bad Request: İstek yanlış formatta veya eksik parametre içeriyor. Genellikle geçersiz JSON yapısı, eksik alanlar veya hatalı veri tipleri sebep olur. İstek gövdenizi kontrol edin.
• 401 Unauthorized: API anahtarı eksik, geçersiz veya süresi dolmuş. Authorization başlığınıza Bearer token'ın doğru yazıldığından emin olun.
• 403 Forbidden: Anahtarınız var ancak bu işlem için yetkiniz yok. API quota'nız dolmuş veya model erişiminiz sınırlandırılmış olabilir.
• 404 Not Found: İstediğiniz endpoint bulunamıyor. URL yapınızı veya model ismini gözden geçirin.
• 429 Too Many Requests: Rate limite takıldınız. Belirli süre içinde çok fazla istek göndermişsiniz. Geriye dönük bekleme stratejisi (exponential backoff) uygulamak iyi bir çözümdür.
• 500 Internal Server Error: Sunucu tarafında bir sorun var. Bu genellikle geçici bir durum olup, birkaç saniye bekleyip tekrar denemek çözüm olabilir.
• 503 Service Unavailable: Servis geçici olarak kullanılamıyor. Yoğunluk veya bakım durumu söz konusu olabilir.

API Özel Hata Yanıtlarını Okumak

HTTP kodunun ötesinde, API'nin döndürdüğü JSON yanıt da önemlidir. Standart bir hata yanıtı genellikle şu yapıdadır:

{
  "error": {
    "message": "Hata açıklaması buraya",
    "type": "invalid_request_error",
    "code": null
  }
}

message alanı hatanın ne anlamға geldiğini açıkça söyler. type alanı ise hatanın kategorisini belirtir. Örneğin:

• invalid_request_error: İsteğinizde bir sorun var, parametre veya format hatası.
• authentication_error: Kimlik doğrulama ile ilgili bir sorun.
• permission_error: Yetki eksikliği.
• rate_limit_error: Hız sınırı aşıldı.
• api_error: Sunucu tarafında beklenmeyen bir hata.

Bu alanları okumak, hatayı çözmek için ilk adımınız olmalıdır.

Hatalarla Baş Etme Stratejileri

Hata kodlarını anlamak kadar onlara nasıl tepki verdiğiniz de önemlidir. İşte uygulayabileceğiniz pratik stratejiler:

• Loglama yapın: Tüm istek ve yanıtları loglayarak hata anında neyin yanlış gittiğini takip edin.
• Geriye dönük bekleme ekleyin: 429 hatası aldığınızda sabit bir bekleme yerine, her denemede bekleme süresini artırın.
• İstekleri doğrulayın: API'ye göndermeden önce istek gövdesinin beklenen şemaya uygun olup olmadığını kontrol eden validasyon katmanı ekleyin.
• Model ve endpoint isimlerini kontrol edin: Yanlış yazılmış model isimleri sıkça 404 veya 400 hatasına yol açar.
• Dokümantasyonu takip edin: Her API'nin kendine özgü sınırlamaları ve davranışları vardır. İlgili platformun resmi dokümanlarını düzenli olarak gözden geçirin.

Hata kodları birer engel değil, sistemi daha iyi anlamanız için verilen işaretlerdir. Doğru okunduklarında geliştirme süreciniz hem daha hızlı hem de daha hatasız ilerler.