Claude API, thinking token'ları max_tokens bütçesini tükettiğinde boş çıktı döndürüyor

İçinde hiçbir şey olmayan bir HTTP 200

dev.to'da Sungwoo Lee tarafından yayımlanan bir yazıya göre Claude API'deki en kafa karıştırıcı hata bir 400, bir 429 ya da bir 529 değil. Text bloğu boş dönen, her şeyin yolunda göründüğü bir HTTP 200. Ne bir exception fırlatılıyor, ne de bir hata olarak loglanıyor; sorunun ilk işareti, downstream'deki bir JSON parser'ının JSON bulamadığını bildirmesi oluyor.

Yazıda anlatılan vakada, bir JSON içerik planı isteyen istek boş bir string döndürmüş. Sebep: thinking token'ları, cevapla aynı max_tokens bütçesinden harcanıyor. 5.369 output token'ının 4.474'ü thinking'e gitmiş, yanıtın kendisine yalnızca 895 kalmış. Çağrı, stop_reason "max_tokens" olarak ayarlanmış ve kesilmiş ya da tamamen eksik bir text bloğuyla sonlanmış; hepsi 200 status kodunun arkasında.

Kaçınılması gereken yanlış teşhis

Yazar, gerçek sebebi bulmadan önce atılan dört adımlık bir yolculuktan bahsediyor. Log, JSON parsing'in başarısız olduğunu söylüyormuş. Ekip, prompt'un modeli JSON yerine düz metne yönlendirdiğini varsaymış ve prompt'u yeniden yazmış. Aynı hata üst üste üç kez geri gelmiş. Ancak o zaman output bütçesini sorunun kaynağı olarak teşhis etmişler.

Yazıya göre ayırt edici unsur ham yanıttır. Prompt modeli gerçekten JSON'dan uzaklaştırmış olsaydı, ham çıktıda yine de metin bulunurdu. Thinking'in bütçeyi tükettiği teşhisini destekleyen tek şey, tamamen boş bir ham string'dir.

Nereye bakmalı ve ne değiştirmeli

Okunacak alan usage.output_tokens_details.thinking_tokens; bunu stop_reason ile birlikte değerlendirmek gerekir. Yazıda belirtildiği gibi streaming yaparken thinking token sayısı yalnızca son message_delta olayında görünür; bu olay incelenmezse gözden kaçması çok kolaydır.

İki resmi çözüm var: thinking ve cevabın ikisinin de sığması için max_tokens değerini yükseltmek, ya da akıl yürütme daha az harcansın diye thinking effort'ı düşürmek. Lee'nin ekibi üçüncüyü ekliyor: tek bir çağrının üretmek zorunda olduğu şeyi küçültmek. Tek seferde tam bir çoklu-gönderi planı istemek yerine, önce bir outline ardından gönderi başına bir içindekiler tablosu istiyorlar ve üç kez başarısız olan çağrı ilk denemede geçiyor. Verilen pratik kural şöyle: çıktının tek parça halinde gelmesi şartsa resmi çözümleri kullanın; bölünebilirse bölün.

Claude hataları için daha geniş bir triaj sırası

Yazı, boş yanıt vakasını genel bir kontrol sırası içinde çerçevelendiriyor:

• error.type'a göre dallanın, asla mesaj metnine göre değil. Anthropic'in dokümantasyonu ifadelerin değişebileceğini söylüyor ve SDK, her status kodu için ayrı bir exception sınıfı fırlatıyor; dolayısıyla mesaj üzerinde string karşılaştırması er ya da geç bozulur.
• 400, isteğin kendisinin hatalı olduğu anlamına gelir ve değiştirilmeden yeniden denemek aynı sonucu verir. Yazının öne çıkardığı, daha yeni modellerdeki tetikleyiciler arasında prefilled assistant mesajları, kaldırılan sabit thinking bütçesi (effort ayarı olan adaptive thinking ile değiştirildi), önceki turlardan düzenlenmiş ya da atılmış thinking blokları ve zorunlu tool_choice ayarları yer alıyor.
• 429 aslında üç farklı sorundur: bir rate limit, usage tier için aylık harcama limiti ya da bir Claude Code workspace harcama limiti. Retry-after header'ı ipucudur. Rate limit'ler bu header'ı gönderir; harcama limitleri göndermez ve erişim yeniden açılana kadar başarısız olmaya devam eder. Bir limiti rate limit sanmak, bütün gün aynı 429'u alan bir backoff döngüsü üretir.
• 529, hesapla değil platform genelindeki bir aşırı yüklenmeyi işaret eder; bu yüzden bekleyip yeniden deneyin. 500 ve 504 için SDK, exception uygulama koduna ulaşmadan önce üstel backoff ile iki kez yeniden denemiş olur; uzun sürebilecek istekler streaming'e ya da batch API'ye aittir.
• Claude Code'da yalnızca oturumdaki ilk çağrısında başarısız olan bir MCP tool'u soğuk başlangıca işaret eder ve yazı MCP_TIMEOUT değerini yükseltmeye işaret ediyor. En keskin uyarısı ise şöyle: zaman aşımına uğrayan bir yazma işlemini asla körü körüne yeniden denemeyin, çünkü zaman aşımı sonucun bilinmediği anlamına gelir ve çoktan gerçekleşmiş bir yazmayı yeniden göndermek değişikliği iki kez uygular.

Neden önemli

Sessiz hatalar, gürültülü olanlardan daha zor yakalanır. Genişletilmiş thinking etkin şekilde Claude çalıştıran, özellikle yapılandırılmış JSON çıktısı bekleyen her pipeline, status kodu kontrolünün neşeyle başarı bildirdiği ama hiçbir şey üretmediği bu moda takılabilir. Her yanıtta thinking_tokens ve stop_reason değerlerini loglamak hatayı görünür kılar. Yazı ayrıca genel olarak iyi bir API hata yönetimini de modelliyor: makine tarafından okunabilir türe göre sınıflandırın, backoff döngüsü yazmadan önce yeniden denenebilir ve denenemez sebepleri ayırın ve bilinmeyen sonuçları onaylanmış hatalardan farklı ele alın.