Hata kodları ve sorun giderme

Neyin başarısız olduğunu belirleyin

1. Gerçek HTTP durumunu, istek yöntemini ve yolu kaydedin. HTTP durumu ile uygulama hata kodu farklı katmanları açıklar; birbirlerinin yerine kullanmayın.
2. Hata alanlarını çağırdığınız protokole göre okuyun. Yerel, OpenAI, Claude ve Gemini yanıtlarının yapısı aynı değildir.
3. Akışlarda hata olaylarını ve tamamlanma durumunu, eşzamansız işlerde status değerini de kontrol edin. HTTP 200, üretimin başarılı olduğunu garanti etmez.
4. İsteği düzeltmek veya yeniden denemeyi değerlendirmek için aşağıdaki tabloyu kullanın. message açıklayıcı metindir, kararlı bir enum değeri değildir; ifadeye göre dallanmayın.

Platform hata kodları enum listesi

Bu, platform uygulama hata kodlarının eksiksiz enum listesidir. Adlar başvuru etiketleridir; yanıtlardaki code değerleri sayıdır. Yaygın HTTP durumu, sorun giderme rehberidir; her uç nokta için sabit bir eşleme değildir. Gerçek HTTP durumunu ve yanıt gövdesini kullanın. Üst sağlayıcıdan doğrudan aktarılan bir code bu listede olmayabilir.

HTTP 429 tek başına hız sınırıyla eşzamanlılık sınırını güvenilir biçimde ayırt etmez. Yalnızca açık bir sayısal hata kodu varsa ayırt edin. Model tanımlayıcılarını model listesinde kontrol edin; model değerlerini kendiniz değiştirmeyin.

Hataları protokole göre okuyun

Aşağıdaki örnekler platformun yaygın olarak ürettiği yapıları gösterir; her hatada garanti edilen tek bir biçim değildir. Kimlik doğrulama hataları farklı işlem katmanlarından gelebilir; doğrudan aktarılan üst sağlayıcı yanıtları kendi yapılarını, dize kodlarını veya türlerini koruyabilir. Ayrıştırmadan önce gerçek yapıyı tanıyın. Bilinmiyorsa dönüşümü zorlamak yerine özgün alanları ve HTTP durumunu koruyun.

Yerel platform API’leri

Genellikle error.code ve error.message alanlarını okuyun. requestId bulunmayabilir.

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

Bazı hatalar üst düzey code ve message alanlarını kullanır. İstemciler bunu desteklemeli ve error nesnesinin bulunmamasını başarı kanıtı saymamalıdır. Parametre doğrulama yanıtlarında da sayısal hata kodu bulunmayabilir. Eksik kodu uydurmak yerine bilinmiyor olarak ele alın.

OpenAI uyumlu API’ler

Yaygın platform hataları üst düzey code, message ve type alanlarını kullanır; mutlaka error içine sarılmış olmaz.

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type protokol kategorisidir; bu yapıda code platformun sayısal hata kodudur. api_error tek başına yeniden deneme uygunluğunu belirlemez. Aktarılan üst sağlayıcı hataları ve akış hataları iç içe bir error içerebilir; gerçek protokol yanıtını işleyin. Chat Completions ve Responses sayfalarına bakın.

Claude uyumlu API’ler

Yaygın yapıda üst düzey type, error değerindedir; ayrıntılı kategori error.type, açıklama ise error.message alanındadır. Bu yapı sayısal bir platform code değeri içermez. Böyle bir kod uydurmayın.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

Platform aşağıdaki Claude hata türlerini yerel olarak üretir. Bu liste tüm üst sağlayıcı hata türlerini kapsamaz.

Claude mesajları sayfasına bakın.

Gemini biçimindeki hatalar

Gemini biçiminde bir yanıtta error.code, error.message ve error.status alanlarını okuyun. Buradaki status, HTTP durumu veya eşzamansız iş durumu değil, dize kategorisidir.

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

Platformun bu yapıda ürettiği hatalar code için platformun sayısal değerlerini kullanır. Dize status alanının yerel eşlemesi aşağıdadır; tüm üst sağlayıcı durumlarını kapsamaz.

503 önceliklidir ve INTERNAL yerine UNAVAILABLE kullanır. Üst sağlayıcı yanıtlarında code ve status farklı anlamlar taşıyabilir. Platform hata kodu tablosunu her sayısal Gemini koduna uygulamayın.

Güvenli yeniden deneme

Geçerli bir Retry-After başlığı varsa ona uyun. Her hatada bu başlığın bulunduğunu varsaymayın. İdempotent olmayan bir üretim isteğini otomatik yeniden denemek onu tekrar yürütebilir ve ek ücrete yol açabilir. Bu sayfa genel bir idempotentlik anahtarı desteği vaat etmez; kendiniz Idempotency-Key eklemeniz yinelenen isteklerin ayıklanmasını garanti etmez.

Zaten bir jobId aldıysanız başka bir iş oluşturmadan önce o işi sorgulayın. jobId yoksa ve sonuç belirsizse inceleme için istek tanımlayıcısını ve zaman damgasını saklayın.

Akışlar ve eşzamansız işler

SSE istekleri

SSE başladıktan sonra HTTP durumu 200 olarak kalabilirken sonraki bir hata akış içinde olay veya veri yükü olarak bildirilebilir. Seçilen protokolün olaylarını ve verilerini ayrıştırın ve normal tamamlanmayı doğrulayın. Hata veya beklenmedik bağlantı kesintisinde kısmi metni ya da görüntüyü tamamen başarılı sonuç saymayın. Olay adları ve veri yükleri uç noktaya göre değişir. Yalnızca sabit bir error alanını kontrol etmeyin ve herhangi bir metin alınmasını başarı saymayın.

Eşzamansız işler

Oluşturma yanıtındaki data.jobId, üretimin tamamlandığını değil kabul edildiğini gösterir. Bir işi sorgularken başarılı HTTP yanıtı, sorgunun başarılı olduğunu gösterir. Yine de işin data.status alanını kontrol etmelisiniz:

• PENDING, CONNECT, PROCESSING: Jobs belgelerine göre sorgulamayı sürdürün.
• COMPLETED: outputResult alanını okuyun.
• FAILED, CANCELLED: sorgulamayı durdurun; inceleme için iş kimliğini ve hassas bilgilerden arındırılmış yanıt verilerini saklayın.

Hata ayrıntıları data.outputResult.error içinde bulunabilir. Bu alan isteğe bağlıdır ve başarısız her işte garanti edilmez. Jobs özelliğini yalnızca oluşturma yanıtı açıkça bir jobId döndürdüğünde kullanın. Sonucu doğrudan JSON veya SSE üzerinden döndüren uç noktalara iş sorgulaması uygulamayın.

Kullanıcılar ve yapay zekâ asistanları için tanılama

Desteğe veya bir yapay zekâ asistanına aşağıdaki hassas bilgilerden arındırılmış bilgileri sağlayın. Eksik alanlar için unknown, HTTP yanıtı alınmadıysa HTTP durumu için de unknown kullanın. error.code: 10000 (number) veya error.code: "invalid_api_key" (string) gibi alan yollarını ve özgün değer türlerini koruyun. Dize biçimindeki bir code değerini otomatik olarak sayısal platform koduna çevirmeyin; eksik alanları message, HTTP durumu veya model adlarından türetmeyin.

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

Varsa requestId değerini yanıt gövdesinden veya X-Request-ID yanıt başlığından okuyun. Uzun sayılarda hassasiyet kaybını önlemek için jobId değerini dize olarak tutun. Yalnızca gerekli en az ve hassas bilgilerden arındırılmış istek parametrelerini paylaşın. API anahtarlarını, belirteçleri, çerezleri, tam kimlik doğrulama başlıklarını, kişisel bilgileri, özel istemleri ve girdi dosyası içeriklerini çıkarın. URL sorgu parametrelerini ve imza veya kimlik bilgisi içeren girdi/çıktı URL’lerini kaldırın. Tam istek günlüklerini incelemeden yapıştırmayın.

Yapay zekâ asistanları gözlemlenen alanlarla olası nedenleri ayırmalı ve eksik bilgileri belirtmelidir. Yetersiz kanıt, isteğin başarılı olduğu, yürütülmediği veya ücret doğurmadığı yönünde kanıt olarak kullanılmamalıdır.