Pada sistem AI internal, bug kuota sering tidak muncul sebagai error besar di awal. Gejalanya justru terlihat sebagai hal yang tampak masuk akal: konsumsi token naik, request sukses, dashboard billing bergerak cepat, lalu tiba-tiba kuota API habis jauh sebelum estimasi. Dalam banyak kasus, masalahnya bukan lonjakan trafik semata, melainkan race condition pada proses pencatatan pemakaian.

Artikel ini membahas studi kasus debug backend race condition kuota API pada layanan AI internal. Konteksnya relevan dengan percepatan adopsi AI: ketika lebih banyak fitur mulai memanggil model, throughput naik, retry makin sering, dan asumsi lama tentang urutan eksekusi backend mulai runtuh. Fokus artikel ini bukan tren AI, tetapi bug nyata yang muncul saat konsumsi resource meningkat lebih cepat daripada kedewasaan kontrol backend-nya.

Kasus yang Terjadi

Sebuah tim memiliki gateway internal untuk mengakses beberapa model AI. Setiap request ke model dicatat ke tabel atau store pemakaian agar ada pembatasan kuota per tim, per service account, atau per proyek. Secara desain, alurnya sederhana:

  1. Request masuk ke API internal.
  2. Sistem membaca sisa kuota.
  3. Jika masih cukup, request diteruskan ke provider AI.
  4. Setelah respons diterima, pemakaian dicatat dan sisa kuota dikurangi.

Secara fungsional, alur ini terlihat benar. Masalah muncul ketika beberapa request paralel dari service yang sama masuk hampir bersamaan. Pada beban rendah, bug tidak terasa. Pada beban tinggi, kuota tercatat lebih banyak atau lebih sedikit dari yang semestinya, lalu sistem mulai membuat keputusan yang salah.

Gejala yang Muncul

  • Kuota API layanan AI internal habis terlalu cepat dibanding estimasi pemakaian aktual.
  • Lonjakan konsumsi tidak selalu sejalan dengan lonjakan jumlah request yang berhasil.
  • Beberapa tim mengeluh mendapat quota exceeded lebih awal, padahal dashboard internal menunjukkan pemakaian yang tampak normal beberapa menit sebelumnya.
  • Retry dari client meningkat karena sebagian request ditolak setelah state kuota menjadi tidak konsisten.
  • Data agregat harian tampak masuk akal, tetapi data granular per menit menunjukkan anomali.

Dampak ke Sistem

  • Gangguan layanan internal: request ke model tertolak lebih cepat.
  • Biaya tak terkontrol: jika pencatatan salah arah, sistem bisa mengizinkan overuse atau menolak request valid.
  • Debugging menjadi mahal: tim infra, backend, dan pengguna internal melihat angka yang berbeda-beda.
  • Kepercayaan pada dashboard turun: metrik observability tidak lagi cukup untuk pengambilan keputusan operasional.

Mengapa Bug Ini Muncul Saat Adopsi AI Meningkat

Saat adopsi AI meningkat, bukan hanya jumlah request yang naik. Pola akses juga berubah:

  • Satu aksi pengguna bisa memicu beberapa panggilan model sekaligus.
  • Pipeline async menambah konkurensi melalui worker, queue, dan callback.
  • Retry otomatis dari client, gateway, atau job runner memperbesar kemungkinan request ganda.
  • Respons model yang lebih lambat memperlebar jendela balapan antar proses.

Dengan kata lain, backend yang sebelumnya aman dalam asumsi serial berubah menjadi sistem dengan banyak penulis (multi-writer) terhadap state kuota yang sama. Jika pencatatan pemakaian dilakukan dengan pola read-modify-write biasa tanpa proteksi konkurensi, race condition sangat mudah terjadi.

Langkah Reproduksi Bug

Agar investigasi tidak berdasarkan dugaan, bug perlu direproduksi. Reproduksi terbaik biasanya dilakukan pada endpoint internal yang memakai akun kuota yang sama.

Pola Implementasi Rentan

Berikut pseudocode yang sering tampak wajar tetapi rawan race condition:

function handleAiRequest(accountId, estimatedCost, payload) {
  quota = quotaRepository.getByAccountId(accountId)

  if (quota.remaining < estimatedCost) {
    return error("quota exceeded")
  }

  response = aiProvider.call(payload)
  actualCost = response.usage.total_tokens

  quota.used = quota.used + actualCost
  quota.remaining = quota.limit - quota.used
  quotaRepository.save(quota)

  return response
}

Masalah utamanya: dua request paralel bisa membaca nilai quota.used yang sama, lalu masing-masing menulis hasil akhir berdasarkan state lama. Salah satu update akan menimpa yang lain, atau keduanya akan meloloskan validasi sebelum kuota diperbarui.

Cara Reproduksi Sederhana

  1. Siapkan akun internal dengan limit kecil agar efek cepat terlihat.
  2. Kirim banyak request paralel menggunakan kredensial yang sama.
  3. Aktifkan retry client atau simulasi timeout ringan untuk memancing duplikasi.
  4. Bandingkan jumlah request sukses, total token provider, dan total token pada store kuota internal.

Contoh perintah beban sederhana:

# ilustrasi, sesuaikan endpoint dan auth
seq 1 50 | xargs -I{} -P 20 curl -s \
  -X POST https://internal-ai.example/api/generate \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"project_id":"proj-a","prompt":"ringkas dokumen"}' > /dev/null

Jika bug ada, hasil akhirnya bisa aneh:

  • provider mencatat 50 request, tetapi store kuota internal mencatat 42 atau 63 unit biaya,
  • request ke-43 kadang lolos, kadang ditolak,
  • nilai remaining sempat negatif atau meloncat.

Log dan Metrik yang Menyesatkan

Bagian tersulit dari bug konkurensi adalah observability yang tampak valid padahal menyembunyikan sumber masalah.

Contoh Sinyal yang Menipu

  • Total request sukses stabil: seolah sistem sehat, padahal state kuota rusak.
  • Latency provider meningkat: tim mudah menyalahkan vendor AI, padahal latency hanya memperbesar peluang race.
  • Grafik agregat per jam terlihat normal: anomali terjadi pada level request atau rentang detik.
  • Error quota exceeded naik setelah deploy: terlihat seperti aturan limit terlalu ketat, padahal issue ada di pencatatan.

Data yang Sebaiknya Dikumpulkan

  • request_id unik untuk setiap request masuk.
  • idempotency_key jika ada retry atau deduplikasi.
  • account_id, project_id, dan unit kuota yang dipakai.
  • Timestamp untuk read quota, provider call start/end, dan quota write.
  • Versi record atau nilai lama-baru saat update kuota.
  • Response usage dari provider bila tersedia.

Dengan log seperti itu, Anda bisa membuktikan bahwa dua worker membaca state yang sama lalu melakukan update yang saling menimpa.

Debugging race condition hampir selalu membutuhkan korelasi per request, bukan hanya dashboard agregat. Jika hanya melihat total harian, akar masalah mudah terlewat.

Root Cause Teknis

Dalam studi kasus ini, akar masalahnya adalah kombinasi beberapa hal:

1. Pola Read-Modify-Write yang Tidak Atomik

Aplikasi membaca quota row, menghitung nilai baru di memory, lalu menyimpannya kembali. Di bawah konkurensi, dua proses dapat bekerja di atas snapshot state yang sama. Akibatnya terjadi lost update.

2. Pencatatan Dilakukan Setelah Provider Merespons

Ini sering dipilih agar biaya aktual berdasarkan token nyata. Namun jeda antara validasi kuota dan pencatatan menjadi lebih panjang. Selama jeda ini, request lain bisa lolos dengan asumsi kuota masih cukup.

3. Retry Tanpa Idempotency

Jika timeout terjadi di sisi client atau gateway, request yang sama bisa dikirim ulang. Tanpa idempotency key, sistem menganggapnya sebagai konsumsi baru. Hasilnya bisa duplikasi pencatatan atau duplikasi panggilan ke provider.

4. Metrik Dibangun dari Sumber yang Berbeda

Dashboard kuota internal mungkin membaca dari database transaksi, sedangkan billing provider memakai laporan usage aktual. Ketika dua sumber tidak direkonsiliasi, selisihnya baru terlihat setelah kuota benar-benar menipis.

Perbaikan yang Benar: Atomic Update, Idempotency, dan Concurrency Control

Tidak ada satu solusi tunggal untuk semua sistem. Biasanya perbaikan yang aman menggabungkan beberapa lapis proteksi.

Atomic Update

Prinsipnya: ubah state kuota langsung di penyimpanan dengan operasi atomik, bukan baca lalu tulis ulang secara naif. Misalnya, alih-alih:

quota = getQuota(accountId)
quota.used = quota.used + actualCost
save(quota)

gunakan pendekatan yang menjamin perubahan terjadi sebagai satu langkah logis di sisi database atau store:

BEGIN TRANSACTION

UPDATE quota
SET used = used + :actualCost,
    remaining = remaining - :actualCost
WHERE account_id = :accountId
  AND remaining >= :actualCost;

-- cek rows affected == 1
-- jika 0, kuota tidak cukup atau state sudah berubah

COMMIT

Mengapa ini bekerja? Karena pengecekan dan update dilakukan dalam satu operasi terhadap state terkini. Ini mengurangi peluang dua request lolos berdasarkan nilai remaining yang sama.

Trade-off:

  • Perlu memastikan unit kuota yang dipakai sudah final saat update dijalankan.
  • Jika biaya aktual baru diketahui setelah respons provider, Anda perlu strategi reservasi atau koreksi pasca-fakta.

Idempotency Key

Untuk request yang mungkin di-retry, setiap operasi konsumsi kuota harus punya identitas deduplikasi. Misalnya client atau gateway mengirim idempotency_key yang unik per aksi logis.

function recordUsage(accountId, requestId, idempotencyKey, actualCost) {
  existing = usageLog.findByIdempotencyKey(idempotencyKey)
  if (existing) {
    return existing.result
  }

  beginTransaction()

  inserted = usageLog.insertIfAbsent({
    accountId,
    requestId,
    idempotencyKey,
    actualCost
  })

  if (!inserted) {
    rollback()
    return usageLog.findByIdempotencyKey(idempotencyKey).result
  }

  updated = quotaRepository.atomicConsume(accountId, actualCost)
  if (!updated) {
    rollback()
    return error("quota exceeded")
  }

  commit()
  return success
}

Mengapa ini penting? Karena race condition sering diperparah oleh retry. Bahkan jika atomic update sudah ada, request duplikat tetap bisa membuat konsumsi berlebih bila tidak dideduplikasi.

Locking: Kapan Perlu Dipakai

Jika satu akun sering menerima banyak request paralel dan aturan kuota cukup kompleks, locking bisa lebih mudah dipahami daripada logika koreksi yang tersebar.

Dua pendekatan umum:

  • Pessimistic locking: ambil lock pada row kuota sebelum menghitung dan mengubah state.
  • Distributed lock: dipakai jika state tersebar atau diproses lintas worker, tetapi harus digunakan hati-hati agar tidak memperkenalkan deadlock atau lock orphan.

Contoh pseudocode dengan row lock:

BEGIN TRANSACTION

SELECT * FROM quota
WHERE account_id = :accountId
FOR UPDATE;

-- hitung apakah cukup
-- update usage dan log

COMMIT

Kapan cocok:

  • kontensi tinggi pada akun yang sama,
  • aturan bisnis sulit diekspresikan dalam satu statement atomik,
  • akurasi lebih penting daripada throughput maksimum.

Kelemahan:

  • menambah latency saat kontensi tinggi,
  • berpotensi menurunkan throughput,
  • perlu timeout dan observability lock wait.

Optimistic Concurrency

Alternatif lain adalah menambahkan kolom versi atau timestamp lalu gagal jika record sudah berubah sejak dibaca.

quota = getQuota(accountId)
newUsed = quota.used + actualCost

updated = UPDATE quota
SET used = :newUsed,
    version = version + 1
WHERE account_id = :accountId
  AND version = :currentVersion;

if updated == 0:
  retry with fresh read

Pendekatan ini cocok jika kontensi tidak terlalu tinggi dan retry aplikasi masih dapat diterima. Jika kontensi sangat sering, optimistic concurrency bisa menghasilkan banyak retry.

Reservasi Dulu, Koreksi Belakangan

Pada integrasi AI, biaya aktual kadang baru diketahui setelah provider merespons. Salah satu desain yang lebih aman adalah:

  1. reservasi kuota berdasarkan estimasi maksimum,
  2. kirim request ke provider,
  3. setelah usage aktual diketahui, lakukan penyesuaian selisih.

Ini mengurangi risiko overspend, tetapi menambah kompleksitas ledger dan rekonsiliasi. Untuk sistem internal yang sensitif terhadap kuota, pendekatan ini sering lebih aman daripada validasi pasca-fakta.

Desain Perbaikan yang Lebih Tahan Bug

Gunakan Ledger, Bukan Hanya Counter Agregat

Menyimpan hanya used dan remaining membuat audit sulit. Simpan juga ledger pemakaian per request. Counter agregat boleh tetap ada untuk performa, tetapi harus dapat direkonstruksi dari ledger.

Keuntungannya:

  • mudah deduplikasi berdasarkan idempotency key,
  • mudah rekonsiliasi dengan usage provider,
  • mudah rollback atau koreksi jika ada bug.

Pisahkan Status Request dan Status Billing

Request sukses ke provider tidak selalu berarti billing internal sukses dicatat. Jika dua status ini dicampur, observability menjadi kabur. Lebih aman jika ada state terpisah, misalnya:

  • accepted
  • provider_completed
  • usage_recorded
  • reconciled

Dengan begitu, backlog pencatatan bisa terdeteksi lebih cepat.

Bangun Rekonsiliasi Berkala

Meskipun path utama sudah aman, tetap sediakan job rekonsiliasi berkala antara ledger internal dan usage provider. Tujuannya bukan menggantikan transaksi yang benar, tetapi menangkap drift sebelum menjadi insiden besar.

Checklist Investigasi Saat Kuota API AI Tiba-Tiba Habis

  • Apakah ada lonjakan request paralel pada akun, proyek, atau service tertentu?
  • Apakah retry dari client, gateway, atau worker meningkat?
  • Apakah ada request yang memiliki payload sama tetapi tanpa idempotency key?
  • Apakah update kuota dilakukan dengan read-modify-write non-atomik?
  • Apakah ada jeda panjang antara validasi kuota dan pencatatan usage?
  • Apakah dashboard mengambil data dari sumber yang berbeda?
  • Apakah ada row lock wait, deadlock, atau retry transaksi yang meningkat?
  • Apakah ledger per request bisa direkonsiliasi dengan data provider?
  • Apakah ada job async yang juga menulis usage untuk request yang sama?
  • Apakah nilai remaining pernah menjadi negatif atau melompat tidak konsisten?

Contoh Alur Perbaikan yang Praktis

Untuk banyak sistem backend internal, kombinasi berikut cukup realistis:

  1. Tambahkan idempotency key pada semua request yang bisa diulang.
  2. Simpan ledger usage dengan constraint unik pada idempotency key atau request external ID.
  3. Lakukan atomic update pada counter kuota dalam transaksi yang sama dengan insert ledger.
  4. Gunakan optimistic concurrency atau row lock jika aturan kuota lebih kompleks.
  5. Tambahkan alerting untuk drift antara usage provider dan usage internal.

Contoh pseudocode end-to-end:

function processAiCall(accountId, idempotencyKey, payload) {
  existing = usageLedger.findByIdempotencyKey(idempotencyKey)
  if (existing) {
    return existing.cachedResponse
  }

  estimatedCost = estimateCost(payload)

  beginTransaction()

  reserved = quotaRepository.atomicReserve(accountId, estimatedCost)
  if (!reserved) {
    rollback()
    return error("quota exceeded")
  }

  usageLedger.insertPending(accountId, idempotencyKey, estimatedCost)
  commit()

  response = aiProvider.call(payload)
  actualCost = response.usage.total_tokens

  beginTransaction()
  usageLedger.markCompleted(idempotencyKey, actualCost, response.metadata)
  quotaRepository.adjustReservation(accountId, estimatedCost, actualCost)
  commit()

  return response
}

Pola ini tidak selalu paling sederhana, tetapi secara operasional lebih tahan terhadap retry, paralelisme, dan selisih biaya aktual.

Alerting yang Sebaiknya Dipasang

Alerting untuk bug kuota tidak cukup hanya memantau error rate. Beberapa sinyal yang lebih relevan:

  • Drift internal vs provider: selisih usage melewati ambang tertentu.
  • Duplicate idempotency attempt: naik tajam dalam periode singkat.
  • Quota update conflict rate: kegagalan update karena versi berubah atau rows affected nol meningkat.
  • Negative balance attempt: ada request yang mencoba membuat kuota negatif.
  • Pending billing state: request yang selesai di provider tetapi belum tercatat secara internal menumpuk.

Alert ini membantu menangkap masalah sebelum pengguna internal melihat kuota habis mendadak.

Pelajaran Desain Backend agar Bug Serupa Tidak Terulang

1. Anggap Kuota sebagai State Finansial

Walaupun ini sistem internal, kuota pada layanan AI berkaitan langsung dengan biaya dan ketersediaan resource. Perlakukan seperti saldo: butuh atomicity, audit trail, dan rekonsiliasi.

2. Jangan Mengandalkan Counter Saja

Counter cepat, tetapi tidak cukup untuk menjelaskan insiden. Ledger per event memberi kemampuan investigasi dan koreksi.

3. Retry Harus Selalu Dianggap Akan Terjadi

Timeout, crash worker, dan retry otomatis adalah kondisi normal dalam sistem terdistribusi. Tanpa idempotency, bug pemakaian ganda hanya masalah waktu.

4. Observability Harus Dibangun untuk Konkurensi

Jika log tidak punya korelasi request, versi record, dan jejak state transition, race condition akan terlihat seperti bug acak yang sulit dibuktikan.

5. Uji dengan Parallel Load, Bukan Hanya Unit Test Biasa

Bug ini sering lolos dari unit test deterministik. Tambahkan integration test atau load test yang menjalankan banyak request bersamaan terhadap akun kuota yang sama.

Penutup

Studi kasus ini menunjukkan bahwa kuota API layanan AI internal yang habis terlalu cepat tidak selalu disebabkan oleh pemakaian berlebih yang nyata. Pada sistem backend yang mulai menangani beban AI lebih tinggi, race condition pada pencatatan pemakaian adalah penyebab yang sangat masuk akal. Solusinya biasanya bukan satu patch kecil, melainkan kombinasi atomic update, idempotency key, locking atau optimistic concurrency, ledger yang bisa diaudit, dan alerting untuk mendeteksi drift.

Jika Anda sedang menangani insiden serupa, mulailah dari dua hal: buktikan race condition dengan log per request, lalu perbaiki jalur update kuota agar tidak bergantung pada asumsi eksekusi serial. Di lingkungan AI yang konsumsi resource-nya terus naik, desain backend semacam ini bukan optimasi tambahan, tetapi syarat dasar agar sistem tetap dapat dipercaya.