Grok 4.6 API İsteklerini Test Etme ve Hata Ayıklama (Akış, Araç Çağrıları, Hatalar)

Grok 4.6, uzun süre çalışan ajanlar için tasarlanmıştır. Bu nedenle entegrasyon hataları genellikle en zor ayıklanan noktalarda görünür: token ortasında takılan akışlı yanıtlar, neredeyse geçerli olan araç çağrısı yükleri ve yalnızca üretim yükünde tetiklenen hız sınırları. xAI belgeleri API’nin kabul ettiği biçimi açıklar; ancak istekleri nasıl doğrulayacağınızı, akışları nasıl inceleyeceğinizi, araç çağrılarını nasıl test edeceğinizi ve CI’da nasıl taklit edeceğinizi anlatmaz. Bu kılavuz, bu iş akışını adım adım uygular.

Apidog'u bugün deneyin

Bu örneklerde çalışma ortamı olarak Apidog kullanılır. Apidog; istek doğrulama, SSE akışlarını görüntüleme, ortam kapsamlı sırları yönetme, yanıt onayları yazma ve sahte sunucular oluşturma işlemlerini tek yerde toplar. Manuel bir kurulumda da aynı ilkeler geçerlidir; yalnızca arayüz adımları değişir.

Özet

• https://api.x.ai/v1 ve XAI_API_KEY için ortam değişkenleri oluşturun; API anahtarını kayıtlı isteklere sabit kodlamayın.
• SSE akışını görsel olarak inceleyin. Parçaların durduğunu mu, yoksa istemcinin render etmeyi mi bıraktığını ayırın.
• tool_calls[].function.arguments alanını JSON olarak ayrıştırın ve her çağrıda şemanıza göre doğrulayın.
• 429 yanıtlarını üstel geri çekilme ile, 5xx yanıtlarını sınırlı sayıda yeniden deneme ile ele alın.
• Her yanıttaki usage nesnesini günlüğe kaydedin.
• CI’da Grok uç noktasını taklit edin; canlı API testlerini gece veya sürüm öncesi çalıştırın.
• Hata ayıklama isteklerini otomatik test senaryolarına dönüştürün.

Önce düzgün bir çalışma alanı kurun

İlk deneme için curl yeterlidir. Ancak başarısız bir isteğin birkaç varyasyonunu karşılaştırmanız gerektiğinde, ortam ve değişken yönetimi kritik hale gelir.

1. Apidog’da Grok 4.6 Entegrasyonu gibi bir proje oluşturun.
2. xai-dev adlı bir ortam ekleyin.
3. Aşağıdaki değişkenleri tanımlayın:

   base_url = https://api.x.ai/v1
   api_key = <anahtarınız>

api_key değişkenini gizli olarak işaretleyin.

1. Aşağıdaki isteği oluşturun:

   POST {{base_url}}/chat/completions
   Authorization: Bearer {{api_key}}
   Content-Type: application/json

1. Geliştirme ortamını xai-prod adıyla kopyalayın ve yalnızca üretim anahtarını değiştirin.

Bu ayrım sayesinde aynı istek koleksiyonunu kullanırken geliştirme deneylerinin üretim kotasını yanlışlıkla tüketmesini önlersiniz.

Henüz API anahtarı oluşturmadıysanız, Grok 4.6 API hızlı başlangıç kılavuzu, console.x.ai kurulumunu ve curl, Python, JavaScript ile ilk istekleri açıklar.

Modeli suçlamadan önce istekleri doğrulayın

Bir istek beklenmedik davranıyorsa önce temel doğrulamaları yapın.

1. Model kimliğini kontrol edin

Yerel xAI API’de model kimliği:

{
  "model": "grok-4-6"
}

Satıcı veya geçit sağlayıcıları farklı adlandırma kullanabilir. Örneğin OpenRouter model kimliği olarak x-ai/grok-4.6 kullanır.

Bir 404 hatası çoğu zaman kesinti değil, yanlış model adı veya yanlış uç noktadır.

2. Parametre aralıklarını doğrulayın

Geçersiz temperature değeri veya bağlam penceresini aşan max_tokens değeri genellikle 400 yanıtı üretir.

Örnek istek gövdesi:

{
  "model": "grok-4-6",
  "messages": [
    {
      "role": "user",
      "content": "Bu kodu açıkla."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 1000
}

Başka parametreleri değiştirmeden önce hata gövdesini okuyun. 400 hatasını yeniden denemek sorunu çözmez.

3. Mesaj dizisini inceleyin

messages dizisi tutarlı olmalıdır. Şu sorunlar hata üretmeden kaliteyi düşürebilir:

• Boş content alanına sahip mesajlar
• Yinelenen sistem istemleri
• Yanlış sırada eklenen araç sonuçları
• Önceki ajan turlarından kalan gereksiz transkriptler

Özellikle ajan döngülerinde gönderdiğiniz tam mesaj dizisini hata ayıklama günlüğüne eklemek faydalıdır.

4. Bağlam penceresi aritmetiğini takip edin

Grok 4.6’nın bağlam penceresi 500K tokendir. Büyük olsa da sınırsız değildir. Uzun ajan transkriptleri ile yüksek max_tokens rezervasyonu birlikte pencereyi aşabilir.

Her yanıttan sonra token kullanımını kaydedin:

function logUsage(response) {
  console.log({
    promptTokens: response.usage?.prompt_tokens,
    completionTokens: response.usage?.completion_tokens,
    totalTokens: response.usage?.total_tokens
  });
}

İstem token sayısı belirlediğiniz eşiğe yaklaştığında uyarı üretin. Böylece sessiz kesintileri üretimde fark etmeden önce yakalayabilirsiniz.

Apidog’un istek doğrulaması; yanlış tür, eksik zorunlu alan ve hatalı gövde yapısı gibi sorunları istek gönderilmeden önce bulmanıza yardımcı olur.

Kör olmadan akış hata ayıklaması yapın

Grok 4.6 yanıtları SSE olarak akabilir. Ajan yanıtları uzun olabileceği için binlerce token içeren akışlar normaldir.

Akış sorunlarını şu üç kategoriye ayırın.

1. Akış duraklıyor

Tokenlar yanıtın ortasında gelmeyi durdurur.

Terminalde bunun modelin üretmeye devam edip etmediğini, ağın mı koptuğunu yoksa istemcinin mi takıldığını anlamak zordur. Apidog’un SSE görünümünde parçaların gerçekten durup durmadığını görebilirsiniz:

• Parçalar hiç gelmiyorsa: sorun sunucu, ağ veya proxy tarafında olabilir.
• Parçalar gelmeye devam ediyor ancak uygulama güncellenmiyorsa: sorun istemcinin okuma veya render kodundadır.

Tarayıcı istemcilerinde ReadableStream tüketimini açıkça yönetin:

const response = await fetch("/api/chat", {
  method: "POST",
  body: JSON.stringify(payload)
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();

  if (done) break;

  const chunk = decoder.decode(value, { stream: true });
  console.log(chunk);
}

2. Akış erken bitiyor

Akış düzgün görünür ancak yanıt beklenenden erken tamamlanır. Son parçadaki finish_reason değerini kontrol edin:

• length: max_tokens sınırına ulaşıldı. Gerekirse artırın.
• stop: Model yanıtı normal olarak tamamladı.

Akış tamamlandığında bu alanı günlüğe kaydedin:

if (chunk.finish_reason) {
  console.log("Akış bitiş nedeni:", chunk.finish_reason);
}

3. Proxy SSE’yi arabelleğe alıyor

İstek yerel ortamda çalışır, ancak hazırlık veya üretim ortamında takılırsa ters proxy yapılandırmasını kontrol edin.

Nginx için akış yolunda örnek yapılandırma:

location /api/chat {
  proxy_pass http://backend;
  proxy_buffering off;
}

Aynı isteği doğrudan ve ağ geçidi üzerinden Apidog’da çalıştırın. Doğrudan bağlantıda akış geliyor, geçit üzerinden gelmiyorsa sorun xAI değil altyapınızdadır.

Araç çağrıları: ajan entegrasyonlarının gerçekten bozulduğu yer

Grok 4.6’nın ajan odaklı kullanımında fonksiyon çağrıları kritik bir bileşendir. Üretim hatalarının önemli bir kısmı metin üretiminden değil, araç çağrısı işleme kodundan kaynaklanır.

Ayrıştırılamayan argümanlar

tool_calls[].function.arguments alanı JSON nesnesi değil, JSON içeren bir dize olarak gelir.

{
  "function": {
    "name": "get_weather",
    "arguments": "{\"city\":\"İstanbul\",\"unit\":\"celsius\"}"
  }
}

Bu değeri savunmacı biçimde ayrıştırın:

function parseToolArguments(rawArguments) {
  try {
    return JSON.parse(rawArguments);
  } catch (error) {
    console.error("Araç argümanları ayrıştırılamadı", {
      rawArguments,
      error: error.message
    });

    throw new Error("Geçersiz araç argümanları");
  }
}

Ayrıştırma hatalarını sayın. Hata oranındaki artış, isteminizde veya araç şemanızda değişen bir şeyin erken sinyali olabilir.

Geçerli JSON, yanlış şema

Argümanlar JSON olarak ayrıştırılabilir; ancak beklediğiniz alanları içermeyebilir.

Örnek araç şeması:

{
  "name": "get_weather",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"]
      }
    },
    "required": ["city"],
    "additionalProperties": false
  }
}

Ayrıştırma sonrası şema doğrulaması uygulayın. Bu doğrulamayı yalnızca geliştirme ortamında değil, üretimde de çalıştırın.

function validateWeatherArgs(args) {
  if (typeof args.city !== "string" || args.city.length === 0) {
    throw new Error("city zorunlu bir dizedir");
  }

  if (args.unit && !["celsius", "fahrenheit"].includes(args.unit)) {
    throw new Error("unit geçersiz");
  }
}

Tanımlanmamış araç çağrıları

Model, tanımlamadığınız bir aracı çağırmaya çalışabilir. Araç adını izin verilen listeye göre doğrulayın:

const tools = {
  get_weather: handleGetWeather,
  search_docs: handleSearchDocs
};

async function executeToolCall(toolCall) {
  const handler = tools[toolCall.function.name];

  if (!handler) {
    throw new Error(`Bilinmeyen araç: ${toolCall.function.name}`);
  }

  const args = parseToolArguments(toolCall.function.arguments);

  return handler(args);
}

Böylece bir KeyError veya undefined is not a function hatasının ajan döngüsünü kontrolsüz biçimde bozmasını engellersiniz.

Akışlı araç çağrılarında parçaları birleştirin

Akışlı yanıtlarda araç argümanları birden fazla parçada gelebilir. JSON ayrıştırma işlemini tüm parçalar birleştirilmeden yapmayın.

const argumentBuffers = new Map();

function appendToolArguments(toolCallId, partialArguments) {
  const current = argumentBuffers.get(toolCallId) ?? "";
  argumentBuffers.set(toolCallId, current + partialArguments);
}

function getCompleteToolArguments(toolCallId) {
  return argumentBuffers.get(toolCallId) ?? "";
}

Erken ayrıştırma, modelin bozuk JSON ürettiği izlenimini verebilir. Oysa sorun çoğu zaman birleştirme kodundadır.

Apidog’da araç çağrısı içeren bir isteği kaydedin ve şu onayları ekleyin:

• Araç adı izin verilen kümede mi?
• arguments alanı JSON olarak ayrıştırılabiliyor mu?
• Ayrıştırılan nesne şemaya uyuyor mu?

LLM çıktıları deterministik olmadığı için aynı senaryoyu birden fazla kez çalıştırın. Tek çalıştırmada görünmeyen %10’luk hata oranı, üretimde hızla görünür hale gelir.

Yığınınız ham fonksiyon çağrıları yerine MCP sunucuları kullanıyorsa aynı disiplin geçerlidir. Ayrıntılar için MCP sunucularını Apidog ile test etme kılavuzuna bakın.

Hatalar, yeniden denemeler ve hız sınırları

Üretim entegrasyonunda her hata sınıfı için açık bir politika belirleyin.

Durum	Anlamı	Politika
400	Hatalı istek	Yeniden denemeyin. Hata gövdesini günlüğe kaydedin ve isteği düzeltin.
401	Geçersiz veya eksik anahtar	Yeniden denemeyin. Ortam değişkenini ve anahtar geçerliliğini kontrol edin.
404	Yanlış model veya uç nokta	Yeniden denemeyin. Model adını ve /v1/models çıktısını doğrulayın.
429	Hız limiti veya kota	Üstel geri çekilme ve titreşimle yeniden deneyin. Varsa Retry-After başlığına uyun.
5xx	Sunucu tarafı hatası	Geri çekilmeyle en fazla 3 kez yeniden deneyin. Sonrasında görevi açık biçimde başarısız yapın.
Zaman aşımı	Uzun üretim veya ağ gecikmesi	Akışı tercih edin. Ajan çağrılarında istemci zaman aşımını saniyeler yerine dakikalar cinsinden belirleyin.

Üstel geri çekilme için örnek:

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function requestWithRetry(requestFn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      const status = error.response?.status;

      const retryable = status === 429 || (status >= 500 && status <= 599);

      if (!retryable || attempt === maxRetries) {
        throw error;
      }

      const baseDelay = 1000 * 2 ** attempt;
      const jitter = Math.floor(Math.random() * 300);

      await sleep(baseDelay + jitter);
    }
  }
}

Her yanıttaki usage nesnesini günlüğe kaydedin. Ajan döngüleri çağrı sayısını hızla artırır; istem değişikliğinden kaynaklanan maliyet regresyonları faturalarda görünmeden önce token günlüklerinde fark edilir.

Maliyet modelinin ayrıntıları için Grok fiyatlandırma analizine bakın.

CI’da Grok’u taklit edin, canlı API’yi ayrı test edin

LLM testlerini hızlı ve uygun maliyetli tutmanın temel kuralı şudur:

CI, her committe canlı modeli çağırmamalıdır.

30 gerçek Grok çağrısı yapan bir ajan entegrasyon testi:

• Gerçek maliyet oluşturur.
• Bir dakikadan uzun sürebilir.
• Sağlayıcıdaki geçici sorunlarda rastgele başarısız olabilir.
• Geliştiricilerin zamanla test sonucunu görmezden gelmesine neden olabilir.

Bunun yerine testleri ikiye ayırın.

Mantık testleri için taklit kullanın

Apidog’un akıllı taklit özelliğiyle Grok biçiminde kontrollü yanıtlar oluşturun:

• Basit tamamlama yanıtı
• Araç çağrısı yanıtı
• 429 yanıtı
• 5xx yanıtı
• Kesilmiş akış
• Geçersiz araç argümanları

Bu sayede aşağıdaki davranışları her committe saniyeler içinde test edebilirsiniz:

• Yeniden deneme mantığı
• JSON ayrıştırma
• Şema doğrulama
• Akış birleştirme
• Döngü sonlandırma
• Hata mesajları

Özellikle hata yanıtlarını taklit edin. Çoğu kod tabanında 429 veya kesilmiş SSE yolu, üretime kadar hiç çalıştırılmamıştır.

Canlı API testlerini programlı çalıştırın

Gerçek API testlerini her committe değil, şu zamanlarda çalıştırın:

• Gece test paketi
• Sürüm öncesi doğrulama
• Model sürümü değişikliği sonrası regresyon testi

Bu paket, gerçek sağlayıcı davranışındaki değişiklikleri yakalar:

• Araç çağrısı biçimindeki farklılıklar
• Yeni hız limiti davranışları
• Model güncellemesi kaynaklı çıktı değişimleri
• Sağlayıcı erişilebilirliği

Apidog test senaryosunu CI için taklit ortama, planlanmış canlı testler için xai-dev ortamına yönlendirin. Aynı onayları iki hedefte de kullanın.

Testleri terminalden veya pipeline içinden çalıştırmak için Apidog CLI ile aynı senaryoları başsız çalıştırabilirsiniz.

Üretim öncesi kontrol listesi

Grok 4.6 trafiğini canlıya almadan önce aşağıdaki maddelerin tamamını doğrulayın:

• [ ] API anahtarları ortam kapsamında tutuluyor; geliştirme ve üretim anahtarları ayrılmış durumda.
• [ ] Hiçbir API anahtarı sürüm kontrolünde yer almıyor.
• [ ] Akış kodu finish_reason: length durumunu ele alıyor.
• [ ] Akış kodu duraklamaları, zaman aşımlarını ve proxy arabelleğini izliyor.
• [ ] Araç çağrısı argümanları her çağrıda savunmacı biçimde ayrıştırılıyor.
• [ ] Araç argümanları şemaya göre doğrulanıyor.
• [ ] Bilinmeyen araç adları açıkça reddediliyor.
• [ ] 429 ve 5xx için yeniden deneme politikası uygulanmış ve taklit ile test edilmiş durumda.
• [ ] Her istek için usage günlüğe kaydediliyor.
• [ ] Görev başına maliyet sapması için uyarı tanımlı.
• [ ] CI taklit ortama karşı çalışıyor.
• [ ] Canlı API test paketi planlanmış olarak çalışıyor.
• [ ] Bir sonraki model sürümünde tüm test paketi tek komutla yeniden çalıştırılabiliyor.

Sıkça Sorulan Sorular

Takılan bir Grok 4.6 akış yanıtını nasıl hata ayıklayabilirim?

İsteği Apidog’un SSE görünümünde yeniden üretin. Parçalar gelmeyi durdurduysa sorun sunucu, ağ veya proxy tarafında olabilir. Parçalar gelmeye devam ediyor ancak arayüz güncellenmiyorsa istemciniz akışı tüketmeyi veya render etmeyi bırakmıştır. Arabelleğe alma ve asenkron işleme kodunu inceleyin.

Grok 4.6 araç çağrıları neden bazen ayrıştırmada başarısız oluyor?

Fonksiyon argümanları JSON nesnesi değil, JSON içeren bir dize olarak gelir. Ayrıca akışlı araç çağrılarında argümanlar parçalar halinde aktarılabilir. Tüm parçaları birleştirmeden JSON ayrıştırmaya çalışmak en yaygın hatalardan biridir. Savunmacı ayrıştırma ve şema doğrulaması uygulayın.

Testlerim gerçek Grok API’sini çağırmalı mı?

Evet, ancak her committe değil. Sağlayıcı davranışındaki değişimleri yakalamak için gece veya sürüm öncesi canlı test paketi çalıştırın. Commit başına testlerde ise uç noktayı taklit edin; böylece CI hızlı, deterministik ve düşük maliyetli kalır.

Bu iş akışı diğer LLM API’leri için de çalışır mı?

Evet. Grok API’si OpenAI uyumlu olduğu için aynı proje yapısında sağlayıcı başına ayrı ortamlar kullanabilirsiniz. Böylece GPT-5.6, Claude ve Grok isteklerini aynı test yaklaşımıyla yan yana doğrulayabilirsiniz.