Cara Menguji dan Debug Permintaan API Grok 4.6 (Streaming, Panggilan Alat, dan Error)

Grok 4.6 dibangun untuk agen yang berjalan lama (long-running agents). Artinya, mode kegagalan integrasi biasanya muncul di area yang paling sulit di-debug: respons streaming yang macet di tengah token, payload panggilan alat (tool call) yang hampir bisa diurai, serta batas laju (rate limit) yang baru terlihat saat beban produksi. Dokumentasi xAI menjelaskan apa yang diterima API, tetapi tidak selalu menjelaskan cara mengujinya. Panduan ini membahas alur kerja untuk memvalidasi permintaan, memeriksa stream, men-debug panggilan alat, menangani error, dan mem-mock respons Grok agar CI tidak menghabiskan token.

Coba Apidog hari ini

Semua langkah di sini menggunakan Apidog sebagai lingkungan kerja karena mendukung rendering SSE, rahasia per lingkungan (environment-scoped secrets), assertion respons, dan mock server dalam satu tempat. Konsepnya tetap dapat diterapkan jika Anda menyiapkannya secara manual.

TL;DR

• Simpan https://api.x.ai/v1 dan XAI_API_KEY sebagai variabel lingkungan. Jangan pernah meng-hardcode API key dalam request yang disimpan.
• Debug streaming secara visual: chunk SSE yang berhenti atau terpotong lebih mudah diidentifikasi.
• Validasi tool_calls[].function.arguments: nilainya adalah string JSON yang harus diurai dan divalidasi terhadap skema Anda.
• Tangani 429 dengan exponential backoff dan 5xx dengan retry terbatas.
• Catat usage pada setiap respons untuk mendeteksi regresi biaya lebih awal.
• Mock endpoint Grok di CI. Jangan menjalankan puluhan panggilan live pada setiap commit.
• Promosikan request debug menjadi skenario pengujian otomatis untuk setiap deployment.

Siapkan Workspace yang Tepat Terlebih Dahulu

Perintah curl ad-hoc cukup untuk hello world, tetapi cepat menjadi sulit dikelola saat Anda perlu membandingkan beberapa variasi request yang gagal.

Siapkan project dan environment berikut:

1. Buat project Apidog, misalnya Grok 4.6 Integration.
2. Buat environment bernama xai-dev.
3. Tambahkan variabel environment:

   base_url = https://api.x.ai/v1
   api_key = <kunci-anda>

Tandai api_key sebagai secret.

1. Buat request:

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

1. Duplikat environment menjadi xai-prod, lalu masukkan key produksi di sana.

Dengan struktur ini, request yang sama dapat dijalankan terhadap dev atau production tanpa risiko eksperimen development menghabiskan kuota production.

Jika Anda belum membuat key, lihat panduan memulai cepat Grok 4.6 API untuk setup console.x.ai serta request pertama dengan curl, Python, dan JavaScript.

Validasi Permintaan Sebelum Menyalahkan Model

Saat request gagal, periksa penyebab paling mendasar terlebih dahulu.

1. Verifikasi ID model

Gunakan ID model yang sesuai dengan provider:

• API native xAI: grok-4-6
• OpenRouter: x-ai/grok-4.6

Status 404 pada tahap ini biasanya berarti ID model atau endpoint salah, bukan pemadaman layanan.

2. Periksa parameter request

Periksa nilai seperti:

• temperature
• max_tokens
• messages
• tools

Nilai temperature di luar rentang atau max_tokens yang melebihi konteks tersisa biasanya menghasilkan 400. Baca body error sebelum mengubah prompt atau kode aplikasi.

Contoh request minimal:

{
  "model": "grok-4-6",
  "messages": [
    {
      "role": "system",
      "content": "Jawab secara ringkas dan teknis."
    },
    {
      "role": "user",
      "content": "Jelaskan cara menangani retry HTTP 429."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 1000
}

3. Audit struktur messages

Pastikan array messages masuk akal:

• Jangan menduplikasi system prompt tanpa alasan.
• Jangan mengirim konten kosong.
• Jangan mencampur riwayat percakapan dari sesi berbeda.
• Pastikan hasil tool sebelumnya dikirim kembali dengan format yang diharapkan aplikasi Anda.

Bug struktur pesan sering menghasilkan jawaban berkualitas rendah tanpa error HTTP, sehingga lebih sulit dideteksi daripada request yang langsung gagal.

4. Hitung penggunaan konteks

Jendela konteks Grok 4.6 adalah 500K token. Nilai ini besar, tetapi loop agen dapat menghabiskannya dengan cepat melalui kombinasi:

• transkrip percakapan panjang;
• hasil tool besar;
• system prompt berulang;
• reservasi max_tokens yang terlalu tinggi.

Catat usage dari setiap respons dan beri peringatan saat token prompt mendekati batas konteks.

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

Validasi request Apidog membantu menangkap kesalahan struktural—seperti tipe field yang salah atau field wajib yang hilang—sebelum request dikirim.

Debug Streaming Tanpa Kehilangan Arah

Respons Grok 4.6 dapat dikirim melalui Server-Sent Events (SSE). Untuk jawaban agentic yang panjang, ribuan token dalam satu stream adalah hal normal.

Fokus pada tiga pola kegagalan berikut.

1. Stream macet di tengah respons

Gejalanya: token berhenti masuk sebelum jawaban selesai.

Di terminal, sulit membedakan apakah model masih memproses atau koneksi memang macet. Di tampilan SSE Apidog, Anda dapat memeriksa apakah event baru masih masuk.

Interpretasinya:

• Chunk berhenti masuk: kemungkinan masalah server, jaringan, proxy, atau timeout.
• Chunk masih masuk tetapi UI aplikasi tidak berubah: kemungkinan masalah di sisi klien, seperti buffering atau consumer async yang berhenti membaca stream.

2. Stream selesai terlalu cepat

Periksa finish_reason pada chunk terakhir:

• length: output mencapai max_tokens; naikkan batas jika respons memang perlu lebih panjang.
• stop: model menyelesaikan respons secara normal.

Pastikan aplikasi Anda menyimpan nilai ini, terutama jika output model harus menyelesaikan langkah agen atau menghasilkan JSON.

if (finishReason === "length") {
  logger.warn("Output terpotong karena max_tokens tercapai");
}

3. Proxy melakukan buffering

Gejalanya:

• Streaming bekerja di lokal.
• Streaming macet atau semua token muncul sekaligus di staging/production.

Reverse proxy sering melakukan buffering secara default. Untuk nginx, pastikan jalur streaming menggunakan konfigurasi seperti:

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

Uji request yang sama dari Apidog terhadap environment lokal dan staging. Jika stream berjalan langsung tetapi gagal melalui gateway, masalahnya ada di infrastruktur, bukan di xAI.

Panggilan Alat: Tempat Integrasi Agen Benar-Benar Rusak

Pemanggilan fungsi adalah komponen penting untuk agen Grok 4.6. Namun, jalur ini juga sering menjadi sumber insiden produksi.

1. Argumen JSON tidak dapat diurai

tool_calls[].function.arguments tiba sebagai string JSON, bukan object JavaScript atau Python.

Contoh payload:

{
  "name": "get_weather",
  "arguments": "{\"city\":\"Jakarta\",\"unit\":\"celsius\"}"
}

Jangan langsung menganggap string tersebut selalu valid. Parse secara defensif:

function parseToolArguments(argumentsText) {
  try {
    return JSON.parse(argumentsText);
  } catch (error) {
    logger.error("Gagal mengurai argumen tool", {
      argumentsText,
      error: error.message
    });

    throw new Error("Tool arguments tidak valid");
  }
}

Pantau tingkat kegagalan parsing. Kenaikan error parsing dapat mengindikasikan perubahan pada prompt, skema, atau pola respons model.

2. JSON valid, tetapi bentuknya salah

JSON yang berhasil diurai belum tentu valid untuk tool Anda.

Contoh masalah:

• field wajib tidak ada;
• string dikirim saat Anda mengharapkan angka;
• enum memiliki nilai yang tidak diizinkan;
• field tambahan tidak dikenal.

Validasi setiap panggilan terhadap skema runtime, bukan hanya saat development.

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

if (typeof args.city !== "string" || args.city.length === 0) {
  throw new Error("Argumen city wajib berupa string");
}

3. Nama tool tidak dikenal

Model kadang dapat menghasilkan nama tool yang tidak Anda definisikan. Tolak secara eksplisit.

const allowedTools = new Set(["get_weather", "search_docs"]);

if (!allowedTools.has(toolCall.function.name)) {
  throw new Error(`Tool tidak diizinkan: ${toolCall.function.name}`);
}

Jangan membiarkan KeyError, undefined is not a function, atau error serupa menghentikan loop agen tanpa konteks yang jelas.

4. Fragmentasi tool call saat streaming

Dalam mode streaming, argumen tool call dapat dikirim dalam beberapa chunk. Gabungkan semua fragmen terlebih dahulu, lalu parse setelah payload lengkap.

Pola sederhananya:

const toolArgumentsByIndex = new Map();

for await (const chunk of stream) {
  for (const toolCall of chunk.choices?.[0]?.delta?.tool_calls ?? []) {
    const current = toolArgumentsByIndex.get(toolCall.index) ?? "";

    toolArgumentsByIndex.set(
      toolCall.index,
      current + (toolCall.function?.arguments ?? "")
    );
  }
}

for (const [index, argumentsText] of toolArgumentsByIndex) {
  const args = parseToolArguments(argumentsText);
  console.log(index, args);
}

Mengurai terlalu awal sering terlihat seperti “model mengeluarkan JSON rusak”, padahal penyebabnya adalah kode perakitan stream yang belum lengkap.

Di Apidog, simpan request yang menghasilkan tool call lalu tambahkan assertion:

• nama tool termasuk daftar yang diizinkan;
• string arguments dapat diurai;
• object hasil parse lolos validasi skema.

Jalankan request beberapa kali. Karena LLM bersifat nondeterministik, kegagalan 10% mudah tersembunyi jika Anda hanya menguji satu eksekusi.

Jika stack Anda menggunakan server MCP, terapkan disiplin yang sama. Lihat panduan menguji server MCP dengan Apidog.

Error, Percobaan Ulang, dan Batas Laju

Terapkan kebijakan eksplisit untuk setiap kategori error berikut.

Status	Makna	Kebijakan
400	Request salah bentuk	Jangan retry. Catat error dan perbaiki request.
401	Key salah atau hilang	Jangan retry. Periksa environment variable dan key di konsol.
404	Model atau endpoint salah	Jangan retry. Verifikasi melalui /v1/models.
429	Rate limit atau kuota	Retry dengan exponential backoff dan jitter. Hormati Retry-After jika tersedia.
5xx	Error sisi server	Retry hingga 3 kali dengan backoff, lalu gagal secara terlihat.
Timeout	Generasi atau jaringan lambat	Gunakan streaming dan atur timeout klien dalam menit untuk request agentic.

Contoh retry untuk 429 dan 5xx:

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;

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

      const baseDelayMs = 1000 * 2 ** attempt;
      const jitterMs = Math.floor(Math.random() * 300);

      await new Promise((resolve) =>
        setTimeout(resolve, baseDelayMs + jitterMs)
      );
    }
  }
}

Dua praktik penting untuk Grok:

1. Siapkan backoff sebelum traffic penting atau demo. 429 dan 5xx sementara dapat terjadi saat beban meningkat.
2. Catat objek usage untuk setiap request. Biaya $2/$6 per juta token memang ramah, tetapi loop agen melipatgandakan penggunaan token.

Dengan logging usage, regresi biaya akibat perubahan prompt biasanya terlihat lebih dulu di metrik sebelum muncul di faktur. Baca analisis harga Grok untuk pembahasan model biaya lebih detail.

Mock Grok di CI, Uji API Live Secara Terpisah

Jangan panggil model live pada setiap commit.

Satu pengujian integrasi agen dapat melakukan 30 request Grok. Jika semua request itu live, pipeline Anda akan:

• membutuhkan biaya nyata;
• berjalan lebih dari satu menit;
• gagal secara acak saat provider mengalami gangguan;
• menjadi cukup lambat sehingga akhirnya diabaikan tim.

Pisahkan pengujian menjadi dua kategori.

Mock untuk logika aplikasi

Gunakan mock Apidog untuk menyajikan respons yang menyerupai Grok, termasuk:

• completion sederhana;
• respons tool call;
• 429;
• 5xx;
• stream terpotong;
• payload tool arguments yang tidak valid.

Dengan mock, jalankan pengujian berikut di setiap commit:

• retry logic;
• parsing JSON;
• validasi skema;
• penghentian agent loop;
• error handling;
• penanganan finish_reason.

Jalur 429 dan stream terpotong sering tidak pernah diuji sampai benar-benar terjadi di production. Mock bentuk kegagalan tersebut secara sengaja.

Pengujian live sesuai jadwal

Jalankan test suite yang memanggil API asli:

• setiap malam;
• sebelum rilis;
• saat mengganti model;
• saat mengubah prompt atau konfigurasi tool.

Tujuannya adalah menangkap provider drift, misalnya perubahan format tool call, rate limit baru, atau perubahan perilaku model, tanpa membuat merge queue bergantung pada availability xAI.

Skenario Apidog dapat menggunakan assertion yang sama untuk dua target:

• environment mock untuk CI;
• xai-dev untuk pengujian live terjadwal.

Jika Anda menjalankan test dari terminal atau pipeline, Apidog CLI dapat menjalankan skenario yang sama tanpa antarmuka grafis.

Daftar Periksa Pra-Produksi

Sebelum traffic Grok 4.6 tayang, pastikan semua item berikut selesai:

• [ ] API key berada di environment scope dan tidak masuk ke version control
• [ ] Environment dev dan production menggunakan key terpisah
• [ ] Streaming menangani finish_reason: length, stream macet, dan buffering proxy
• [ ] Argumen tool call diurai secara defensif
• [ ] Setiap argumen tool call divalidasi terhadap skema
• [ ] Nama tool yang tidak dikenal ditolak secara eksplisit
• [ ] Kebijakan retry 429 dan 5xx sudah diimplementasikan
• [ ] Jalur retry diuji melalui mock
• [ ] usage dicatat per request
• [ ] Ada peringatan untuk kenaikan biaya per task
• [ ] CI menggunakan mock endpoint
• [ ] Test suite live berjalan terjadwal
• [ ] Seluruh suite dapat dijalankan kembali dalam satu perintah saat model berikutnya dirilis

FAQ

Bagaimana cara men-debug respons streaming Grok 4.6 yang menggantung?

Reproduksi request di tampilan SSE Apidog. Jika chunk berhenti datang, periksa jaringan, proxy, dan timeout. Jika chunk masih datang tetapi aplikasi tidak merendernya, periksa buffering serta konsumsi stream async di sisi klien.

Mengapa panggilan alat Grok 4.6 terkadang gagal diurai?

Argumen fungsi tiba sebagai string JSON dan, pada streaming, dapat terfragmentasi ke beberapa chunk. Gabungkan fragmen terlebih dahulu, lalu parse secara defensif dan validasi hasilnya terhadap skema.

Haruskah pengujian saya memanggil API Grok yang sebenarnya?

Ya, tetapi hanya sesuai jadwal seperti nightly atau pre-release untuk menangkap provider drift. Untuk setiap commit, gunakan mock endpoint agar CI tetap cepat, deterministik, dan gratis.

Apakah alur kerja ini berfungsi untuk API LLM lainnya?

Ya. Karena API Grok kompatibel dengan OpenAI, struktur project Apidog yang sama dapat digunakan untuk beberapa provider dengan environment terpisah. Pendekatan ini juga dapat dipakai untuk GPT-5.6, Claude, dan Grok dalam perbandingan antar-model.