OpenAI API isteği başarısız olduğunda yalnızca hata metnine bakarak yeniden denemek yeterli değildir. HTTP durum kodu, yanıt gövdesindeki error.code ve varsa Retry-After başlığı birlikte değerlendirilmelidir. İstek kimliğini loglamak, destek gerektiğinde sorunun bulunmasını kolaylaştırır; API anahtarını loglamayın.
400: İstek biçimi veya parametre sorunu
Gönderilen JSON, model adı, zorunlu alanlar ve seçilen uç noktanın kabul ettiği parametreler kontrol edilmelidir. Yanıtın hata alanındaki parametre bilgisi hangi değerin reddedildiğini gösterebilir. Aynı hatalı isteği aralıksız yinelemek sorunu çözmez. Özellikle daha önce çalışan bir kod bozulduysa kullanılan SDK sürümü ile resmi API referansındaki örneği karşılaştırın.
401 ve 403: Yetki sorunu
401 için proje anahtarının doğru ortamdan yüklendiğini, silinmediğini ve başına/sonuna boşluk eklenmediğini doğrulayın. Anahtarı tarayıcıya veya herkese açık depoya koymayın. 403 görüldüğünde proje izni, model erişimi ve yanıtın belirttiği kısıtı inceleyin. Yeni anahtar oluşturmak, izin veya bölge kısıtını tek başına çözmez.
429: Hız sınırı mı, kullanım sınırı mı?
429 farklı nedenlerle dönebilir: kısa sürede çok fazla istek, token sınırı, ani trafik artışı veya kullanım/kredi sınırı. error.code alanına bakın. Geçici hız sınırında Retry-After varsa en az o süre kadar bekleyin; yoksa üstel artan bekleme ve küçük rastgele gecikme kullanın. Yeniden deneme sayısını sınırlayın. Kredi veya harcama sınırı aşıldıysa beklemek yerine proje kullanım ayarlarını incelemek gerekir.
5xx ve bağlantı zaman aşımı
Sunucu hataları ve geçici bağlantı sorunlarında sınırlı yeniden deneme uygundur. Zaman aşımında ilk isteğin işlenip işlenmediği belirsiz olabilir; ücretli veya yan etkisi olan iş akışlarında mükerrer işlemleri önleyecek kayıt mekanizması kurun. Kullanıcıya anlaşılır bir hata gösterin ve teknik ayrıntıyı sunucu logunda saklayın.
Üretim için kısa kontrol listesi
- HTTP kodunu,
error.codedeğerini ve istek kimliğini kaydedin. - Gizli anahtarları, tam kullanıcı girdilerini ve hassas verileri loglamayın.
- Yalnızca geçici hatalarda, sınırlı sayıda yeniden deneyin.
- İstek ve token tüketimini proje sınırlarına göre izleyin.
- Boş yanıt, kısmi akış ve zaman aşımını uygulama arayüzünde ele alın.
Kaynaklar: OpenAI API hata kodları; hız sınırları.
