P
PUGUH
EN Get Started

Pemecahan Masalah

Masalah umum dan cara mengatasinya.

Masalah Autentikasi

"Invalid or expired token"

Token JWT telah kedaluwarsa atau formatnya salah.

Solusi:

  1. Periksa waktu kedaluwarsa token
  2. Refresh token
  3. Autentikasi ulang jika refresh gagal
typescript 
try {
  await client.organizations.list();
} catch (error) {
  if (error.code === 'TOKEN_EXPIRED') {
    await client.auth.refresh();
    await client.organizations.list(); // Retry
  }
}

"API key not found"

API key tidak valid atau telah dicabut.

Solusi:

  1. Verifikasi API key sudah benar
  2. Periksa apakah key telah dirotasi
  3. Pastikan key untuk organization yang benar

"Permission denied"

User tidak memiliki permission yang diperlukan.

Solusi:

  1. Periksa role user di IAM
  2. Verifikasi permission yang diperlukan
  3. Minta peningkatan role jika diperlukan
typescript 
// Check required permission
const hasPermission = await client.checkPermission('webhook.endpoints.create');
if (!hasPermission) {
  console.log('Contact your admin to request access');
}

Masalah Organization

Tidak Dapat Membuat Organization

Anda mungkin telah mencapai limit organization untuk paket Anda.

Solusi:

  1. Periksa limit organization pada paket Anda saat ini
  2. Upgrade paket jika diperlukan
  3. Hubungi support untuk limit enterprise

Undangan Anggota Tidak Berfungsi

Email undangan tidak diterima atau undangan gagal.

Langkah Debugging:

  1. Periksa apakah alamat email sudah benar
  2. Periksa folder spam/junk
  3. Verifikasi paket Anda mengizinkan lebih banyak anggota
  4. Periksa apakah user sudah menjadi anggota

Masalah Webhook

Webhook Tidak Menerima Event

Sistem eksternal tidak menerima event webhook.

Langkah Debugging:

  1. Verifikasi webhook aktif di pengaturan Webhooks
  2. Periksa URL webhook dapat dijangkau (HTTPS diperlukan)
  3. Tinjau riwayat pengiriman untuk respons error
  4. Uji dengan endpoint ping
typescript 
// Send a test ping
const result = await client.webhooks.test(webhookId);
console.log(result.status); // Check delivery status

Verifikasi Signature Webhook Gagal

Secret salah atau parsing payload tidak tepat.

Solusi:

typescript 
// Verify using the secret from webhook creation
const isValid = verifyWebhookSignature(
  req.rawBody, // Use raw body, not parsed JSON
  req.headers['x-puguh-signature'],
  webhookSecret
);

Masalah Performa

Respons API Lambat

Waktu respons API lebih tinggi dari yang diharapkan.

Debugging:

1. Periksa Latensi Jaringan

  • Gunakan endpoint API regional
  • Pertimbangkan caching untuk request yang berulang

Rate Limiting

Error 429.

Solusi:

1. Periksa Penggunaan

typescript 
const metrics = await client.control.getMetricsTrends({ period: '7d' });
console.log(`Events: ${metrics.totalEvents}`);

2. Implementasikan Logika Retry

typescript 
const client = new PuguhClient({
  retries: 3,
  retryDelay: 1000,
});

3. Batch Request

typescript 
// Instead of individual calls
const decisions = await client.decideBatch(requests);

4. Upgrade Paket - Paket lebih tinggi memiliki rate limit lebih tinggi.

Masalah Data

Entri Audit Hilang

Event yang diharapkan tidak muncul di jejak audit.

Periksa:

1. Rentang Waktu - Perluas rentang tanggal dalam query. Periksa pengaturan timezone.

2. Filter Application - Event mungkin ada di application lain. Periksa scope application.

3. Tipe Event - Verifikasi Anda memfilter tipe event yang benar.

Celah Audit Log

Entri yang hilang di jejak audit.

Penyebab:

  1. Periode Retensi - Paket Free: 7 hari. Periksa retensi paket Anda.
  2. Pengaturan Filter - Hapus filter untuk melihat semua entri. Periksa filter tipe aksi.
  3. Export Log Terarsip - Hubungi support untuk log lama (Enterprise).

Masalah Integrasi

Webhook Tidak Terpicu

Sistem eksternal tidak menerima event.

Debugging:

1. Periksa Status Webhook - Buka Settings > Webhooks. Periksa status kesehatan webhook.

2. Verifikasi Endpoint - Pastikan URL dapat dijangkau. Periksa persyaratan HTTPS.

3. Periksa Signature

typescript 
// Your webhook handler
const isValid = verifyWebhookSignature(
  req.body,
  req.headers['x-puguh-signature'],
  webhookSecret
);

4. Tinjau Log Webhook - Control > Events menampilkan percobaan pengiriman webhook. Periksa respons error.

Masalah Koneksi SDK

Panggilan SDK timeout atau gagal.

Periksa:

1. Konektivitas Jaringan

bash 
curl https://api-puguh.arsaka.io/health

2. Aturan Firewall - Pastikan HTTPS keluar diizinkan. Periksa pengaturan proxy korporat.

3. Konfigurasi SDK

typescript 
const client = new PuguhClient({
  timeout: 30000, // Increase timeout
  baseUrl: 'https://api-puguh.arsaka.io', // Correct URL
});

Mendapatkan Bantuan

Jika Anda tidak dapat menyelesaikan masalah:

  1. Periksa Halaman Status: https://status.arsaka.io
  2. Tinjau Dokumentasi: Cari di dokumentasi
  3. Hubungi Support: support@arsaka.io
  4. Sertakan Detail:
    • Organization ID
    • Timestamp masalah
    • Pesan error
    • Langkah reproduksi

Terkait