Menu dokumentasi

Keamanan, Batasan & Error

Menjaga API Key, batasan server, percobaan ulang otomatis, dan arti setiap pesan error.

Keamanan

API Key adalah kunci project Anda. Siapa pun yang memegangnya bisa membuat dan membatalkan tagihan atas nama Anda.

  • Simpan API Key di berkas konfigurasi klien di komputer Anda, di variabel lingkungan server, atau di penyimpanan rahasia. Jangan tempel di repositori publik, di dalam percakapan dengan chatbot, atau di kode yang berjalan di browser.
  • Bila API Key bocor, hapus key itu di Dashboard → Projects → API Keys, lalu buat yang baru.
  • Pakai satu API Key per chatbot atau integrasi, supaya satu key yang bocor bisa dicabut tanpa mengganggu yang lain.

Yang disimpan server. MCP Server tidak menyimpan API Key, tagihan, atau data pelanggan. Untuk setiap permintaan, server mencatat satu baris log berisi IP pengirim, sidik jari API Key (10 karakter dari hash SHA-256, bukan key-nya), nama tool, status, dan lama proses.

Yang bisa dilakukan lewat MCP Server hanya enam tool. Tidak ada akses ke saldo, penarikan dana, pengaturan project, KYC, atau daftar transaksi.

Semua sambungan lewat HTTPS. Server menolak permintaan tanpa header Authorization dengan 401.

Chatbot yang melayani pelanggan

Bila pelanggan bisa mengobrol langsung dengan chatbot (mis. bot WhatsApp), pelanggan juga bisa mencoba membujuknya. Beberapa langkah yang disarankan:

  • Batasi tool. Bot pelanggan biasanya cukup create_payment_link, get_payment_status, dan list_payment_methods. Matikan cancel_payment bila klien Anda mendukungnya (mis. Tools to Include → Selected di n8n), atau minta persetujuan admin untuk tool itu.
  • Tentukan nominal dari sistem Anda. Untuk harga tetap, sebutkan daftar harga di prompt sistem atau ambil dari katalog Anda, jangan dari kata-kata pelanggan.
  • Jangan memproses pesanan dari ucapan chatbot. Kirim barang atau buka akses hanya dari webhook atau status paid.

Batasan

Batasan Nilai
Nominal per tagihan Rp1.000–Rp500.000.000, bilangan bulat. Batas metode pembayaran project tetap berlaku.
order_id 1–255 karakter, unik per project.
customer_name / description Maks. 100 / 200 karakter.
Tagihan per panggilan list_unpaid_bills 50
Cek status per tagihan 30 kali per menit (batas Aulaa API).
remind_every_minutes 1–43.200 menit (30 hari).
send_within_minutes 1–60 menit, bawaan 5.
Ukuran permintaan Maks. 1 MB.
Batas waktu ke Aulaa API 15 detik per permintaan.

Server memakai mode stateless: setiap permintaan berdiri sendiri, tanpa sesi. Hanya POST /mcp yang dilayani.

Percobaan ulang otomatis

Gangguan sesaat dicoba ulang otomatis paling banyak 2 kali, dengan jeda yang makin panjang:

  • tidak bisa menghubungi Aulaa API (jaringan putus, batas waktu),
  • 502, 503, 504,
  • 429 dengan Retry-After paling lama 5 detik.

Ini berlaku untuk membuat tagihan, cek status, pengingat, dan daftar metode. Membuat tagihan aman dicoba ulang karena order_id yang sama tidak pernah membuat tagihan kedua. Pembatalan tidak dicoba ulang.

Error dari tool

Bila Aulaa API menolak, hasil tool bertanda isError: true dan teksnya berisi kode HTTP, pesan dari Aulaa, dan saran:

Aulaa API error (HTTP 401): invalid API key
API Key Aulaa tidak valid/kedaluwarsa. Merchant perlu membuat API Key baru di Dashboard → Projects.
Kode Penyebab Yang perlu dilakukan
0 Aulaa API tidak terjangkau (jaringan atau batas waktu). Coba lagi sebentar lagi.
400 Nominal atau kode metode tidak valid. Periksa nominal dan kode di list_payment_methods.
401 API Key salah, sudah dihapus, atau bukan milik project ini. Buat API Key baru di Dashboard → Projects.
403 Project bertipe No-Code, atau akun/project sedang dibekukan. Pesan dari Aulaa menyebut penyebabnya. Ubah tipe project ke API, atau cek status akun dan project di Dashboard.
404 Tagihan tidak ditemukan di project ini. Pakai id dari Aulaa (payment_id), bukan order_id.
409 Aksi tidak cocok dengan status tagihan, mis. membatalkan tagihan yang sudah lunas. Cek status dulu dengan get_payment_status.
429 Terlalu sering dicek. Teks error menyertakan Retry-After. Tunggu sebelum mencoba lagi.
5xx Gangguan di server Aulaa. Coba lagi nanti.

Kode lengkap dari Aulaa API ada di Kode Error.

Input ditolak sebelum sampai ke Aulaa

Input yang salah bentuk ditolak MCP Server tanpa memanggil Aulaa. Klien menerima error MCP -32602, misalnya:

MCP error -32602: Input validation error: Invalid arguments for tool get_payment_status: payment_id harus UUID dari Aulaa (field `id`), bukan order_id at payment_id

Penyebab yang paling sering:

  • payment_id diisi order_id. payment_id selalu berbentuk UUID, mis. f47ac10b-58cc-4372-a567-0e02b2c3d479.
  • amount berdesimal atau memakai titik ribuan sebagai teks. Tulis 150000, bukan "150.000" atau 150000.5.
  • payment_method memakai huruf besar. Kode metode selalu huruf kecil, mis. qris, bca_va.
  • last_reminded_at tanpa zona waktu. Pakai ISO 8601 lengkap, mis. 2026-11-18T02:00:00Z.

Error di tingkat HTTP

Error ini muncul sebelum tool dijalankan, biasanya karena konfigurasi klien:

HTTP Pesan Penyebab
401 Unauthorized: kirim 'Authorization: Bearer <API Key Aulaa pgw_...>' Header Authorization tidak ada atau tidak diawali Bearer.
405 Method not allowed Klien memakai GET. Pakai POST. Klien MCP resmi menanganinya sendiri.
406 Not Acceptable: Client must accept both application/json and text/event-stream Header Accept kurang lengkap (biasanya saat tes dengan cURL).
400 Parse error: invalid JSON Isi permintaan bukan JSON yang valid.
413 Request body too large Isi permintaan lebih dari 1 MB.

API Key yang formatnya benar (pgw_...) tapi salah tetap lolos pemeriksaan header, lalu ditolak Aulaa API dengan 401 di hasil tool. Jadi bila koneksi berhasil tapi setiap tool gagal dengan 401, periksa API Key-nya.

Terakhir diperbarui 17 November 2026