Hata yönetimi

Hatalar size iki farklı yoldan ulaşır ve bu fark, onları nasıl ele alacağınızı belirler. Bir istek sohbet işleyicisine girmeden önce başarısız olursa, bu durum kodu taşıyan sıradan bir HTTP hatasıdır. Girdikten sonra başarısız olursa, bir 200 OK olay akışının içinde bir olay olarak gelir; çünkü işleyici, herhangi bir iş yapmadan önce başlıklarını gönderir. Yalnızca response.ok değerine bakan bir istemci ikinci türü hiç görmez.

Hata gövdesi tek biçimli değildir

Ağ geçidinde genel bir istisna filtresi yoktur; bu nedenle aldığınız gövde, hatayı hangi kod parçasının fırlattığına bağlıdır. Dolaşımda üç biçim vardır.

Bir çerçeve istisnası, örneğin başarısız bir doğrulama veya reddedilen bir belirteç. code alanı yoktur:

{
  "statusCode": 401,
  "message": "Invalid or expired token",
  "error": "Unauthorized"
}

Genel doğrulama işlem hattı gövdeyi reddettiğinde message, başarısız her kısıt için bir tane olmak üzere bir dizi olur:

{
  "statusCode": 400,
  "message": ["model must be a string", "messages should not be empty"],
  "error": "Bad Request"
}

Makine tarafından okunabilir bir kod ve durum taşıyan bir koruma. Bunlar code ve bazen ek bağlam ekler, error alanını ise düşürür:

{
  "statusCode": 403,
  "code": "FEATURE_NOT_LICENSED",
  "feature": "ldap",
  "tier": "standard",
  "message": "This feature (ldap) is not included in the installed license tier. Contact your CID representative to upgrade."
}

Bir rol reddi; yalnızca code ve message taşır, başka hiçbir şey — statusCode bile yok. Durumu gövdeden değil, HTTP yanıt satırından okuyun:

{
  "code": "READ_ONLY_ROLE",
  "message": "This is a read-only demo account (viewer role) — actions and changes are disabled."
}

İstemcinizi code, statusCode ve error alanlarının tümünü isteğe bağlı sayacak ve statusCode yokken HTTP durumuna geri dönecek biçimde yazın.

HTTP durum kodları

Kimlik doğrulama hataları

Ağ geçidi, aynı başlık üzerinde ya bir kullanıcı JWT'si ya da bir ağ geçidi API anahtarı kabul eder. Reddetmelerinin hepsi birbirine benzer:

{
  "statusCode": 401,
  "message": "Missing or invalid authorization header",
  "error": "Unauthorized"
}

Görebileceğiniz mesajlar şunlardır: Missing or invalid authorization header, Invalid token, Invalid or expired token, Invalid API key ve Invalid or expired API key. Bunlardan birini aldığınızda:

• Başlığın Bearer önekiyle birlikte Authorization: Bearer <credential> olduğunu doğrulayın. X-API-Key başlığı yoktur.
• Anahtarın hâlâ cid_key_ ile başladığını ve yeniden oluşturulmadığını doğrulayın. Yeniden oluşturma önceki değeri anında geçersiz kılar.
• JWT'nin süresinin dolmadığını ve iptal edilmediğini doğrulayın. Belirteçler JWT_EXPIRES_IN boyunca, varsayılan olarak 24 saat yaşar; çıkış, parola değişikliği, yöneticinin Her yerden çıkış yap komutu veya hesabın devre dışı bırakılması ile daha erken sona erer (code: SESSION_EXPIRED).
• Uç noktanın kullandığınız kimlik bilgisini kabul ettiğini doğrulayın. /sessions/*, /image-analysis/* ve /document-analysis/* yalnızca JWT kabul eder; bir API anahtarı /chat/completions ve /models üzerinde çalışsa bile burada reddedilir.

code: "ROLE_NOT_FOR_CHAT" taşıyan bir 403 kimlik doğrulama hatası değildir. auditor rolü sohbet ve oturum yazma işlemlerinde tasarım gereği reddedilir ve aynı belirteçle yeniden denemek başarılı olamaz.

Engellenen içerik

İçerik politikası kararları HTTP hatası değildir. Sohbet yüzeyinde akış olayı, tespit yüzeyinde ise bir action alanı taşıyan başarılı bir yanıttır.

Sohbet, girdi reddedildi. İstem sağlayıcıya hiç ulaşmaz, dolayısıyla token harcanmaz:

data: {"error":"Content policy violation: hate","type":"content_rejected","entities":[{"type":"hate","action":"reject","confidence":0.94}]}

data: [DONE]

Sohbet, yanıt reddedildi — model yanıtladıktan sonra çıktı filtresi tarafından. Yanıt atılır ve hiç gönderilmez:

data: {"type":"output_content_rejected","severity":"critical","message":"🚫 Response blocked due to policy violations","reason":"Content policy violation: pii_leak","entities_detected":2,"actions_applied":["reject"]}

data: [DONE]

Oturum mesajları farklı reddeder. POST /sessions/:id/messages kendi girdi reddini hiç error alanı olmadan yayar; bu nedenle error alanına bakan bir işleyici bunu kaçırır:

data: {"type":"content_rejected","reason":"Content policy violation: hate","categories":{"hate":true},"scores":{"hate":0.94},"filter":"content-safety-v2 v2","filter_duration_ms":148}

data: [DONE]

Tespit uç noktası. POST /api/v1/guardrails/detect 200 döndürür ve kararı gövdede belirtir:

{
  "action": "reject",
  "detectionCount": 1,
  "detectedEntities": [
    { "type": "hate", "value": "[REDACTED]", "action": "reject", "confidence": 0.94, "source": "hap_detector" }
  ],
  "maskedText": "…",
  "processingTimeMs": 142
}

Akışı güvenle okumak

Akıştan yapılan tek bir okuma birkaç data: çerçevesi ya da bir çerçevenin yarısını getirebilir. Çözülmüş metni tamponlayın ve tek bir okumanın döndürdüğünü ayrıştırmak yerine çerçeve sınırından bölün. Dört şeyi ele alın: sonlandırıcı [DONE], bir error alanı, tipli reddetme olayları ve tek içerik olayı.

async function readGatewayStream(response, onAnswer) {
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';
 
  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });
 
      // Frames are separated by a blank line; keep the trailing partial frame.
      const frames = buffer.split('\n\n');
      buffer = frames.pop() ?? '';
 
      for (const frame of frames) {
        const line = frame.split('\n').find((l) => l.startsWith('data: '));
        if (!line) continue;
        const data = line.slice(6).trim();
        if (data === '[DONE]') return;
 
        const event = JSON.parse(data);
 
        // Input block on /chat/completions, and any unhandled server error.
        if (event.error) throw new Error(event.error);
 
        // Input block on /sessions/:id/messages — no `error` field.
        if (event.type === 'content_rejected') throw new Error(event.reason);
 
        // Output filter discarded the answer.
        if (event.type === 'output_content_rejected') throw new Error(event.reason);
 
        if (event.type === 'output_content_warning') {
          console.warn('Flagged:', event.message);
          continue;
        }
 
        // The whole filtered answer, as one event.
        if (!event.type && typeof event.content === 'string') onAnswer(event.content);
      }
    }
  } finally {
    reader.releaseLock();
  }
}

Bağlantı, içerik olayından önce akış ortasında kopar ise kurtaracak kısmi bir yanıt yoktur — cevap tek parça hâlinde yayılır. Kesilen bir akışı başarısız bir çağrı sayın.

Hangi hatalar yeniden denenir

Sınırlar ve bilinen eksikler

• Tek biçimli hata zarfı yok. Üç gövde biçimi bir arada bulunur ve yalnızca korumaların ürettiği hatalar code taşır. code alanını zorunlu sayan bir istemci yazmayın.
• İçerik kararları için hata kodu sınıflandırması yok. Bir engelleme, üzerinde dallanma yapabileceğiniz kalıcı bir kodla değil, bir olay tipi ve serbest metinli bir reason ile anlatılır.
• Sohbet hataları 200'ün arkasına saklanır. 2xx dışı yanıtları sayan izleme, /chat/completions üzerindeki bir sağlayıcı kesintisini başarı olarak kaydeder.
• İki sohbet yüzeyi birbiriyle uyuşmaz. /chat/completions girdiyi bir error alanıyla reddeder; /sessions/:id/messages ise type: "content_rejected" ve bir reason ile. Ortak bir istemcinin her ikisini de ele alması gerekir.
• Genel sohbet hata mesajı belirsizdir. Denetleyicideki ele alınmamış bir istisna, hiçbir ayrıntı içermeyen {"error":"An error occurred"} yazar; nedeni yalnızca ağ geçidi günlüğündedir.
• Hız sınırı bildirimi yok. Yalnızca oturum açma rotaları sınırlı olduğu için, istek yolunda bir istemciyi hizalayabileceğiniz bir kota başlığı yoktur.

İlgili sayfalar

• En iyi uygulamalar — kimlik bilgisi yönetimi, yeniden deneme politikası ve tamponlanan akışın arayüzünüz için anlamı.
• Entegrasyon örnekleri — burada gösterilen ele alma biçimini uygulayan istemciler.
• Sohbet API'si — /chat/completions için tam olay listesi.