Apa arti kode galat API SekaliPay?

Galat dikenali dari status HTTP dan kodenya. Kode ada di error_code untuk galat autentikasi dan batas permintaan, dan di message untuk galat dari endpoint. Galat validasi field memakai status 422 dengan daftar errors per field dan tanpa kode.

Isi halaman ini dicocokkan dengan kode API per 16 Oktober 2026.

Ada berapa bentuk respons galat?#

Bentuk	Muncul saat	Kode ada di
Autentikasi dan batas	API key, IP, tanda tangan, atau batas permintaan bermasalah	`error_code`
Endpoint	Aturan bisnis endpoint menolak permintaan	`message`
Validasi (`422`)	Field permintaan tidak valid	Tidak ada kode; lihat `errors`

{
  "success": false,
  "message": "Access denied. Your IP address is not whitelisted.",
  "your_ip": "203.0.113.10",
  "error_code": "IP_NOT_WHITELISTED"
}

{
  "status": false,
  "message": "AMOUNT_OUT_OF_RANGE",
  "data": {
    "min_amount": 10000,
    "max_amount": 10000000
  }
}

{
  "message": "Amount must be an integer",
  "errors": {
    "amount": [
      "Amount must be an integer"
    ]
  }
}

Selalu kirim Accept: application/json

Tanpa header ini, galat validasi dibalas pengalihan 302 ke beranda SekaliPay, bukan JSON 422. URL yang salah dibalas halaman HTML 404.

Apa saja kode galatnya?#

HTTP	Kode	Arti
401	MISSING_API_KEY	Header `X-API-Key` tidak dikirim.
401	INVALID_API_KEY	API key salah, sudah diganti, atau akun tidak aktif.
403	IP_WHITELIST_NOT_CONFIGURED	Mode IP Whitelist aktif tetapi belum ada IP terdaftar. Tambahkan IP, atau matikan whitelist untuk memakai Enhanced HMAC.
403	IP_WHITELIST_INVALID	Konfigurasi whitelist akun rusak. Hubungi dukungan.
403	IP_NOT_WHITELISTED	IP pengirim tidak terdaftar. Daftarkan IP yang tertera di `your_ip`.
401	MISSING_SIGNATURE	Permintaan POST di mode IP Whitelist tanpa header `X-Signature`.
401	INVALID_SIGNATURE	Tanda tangan body tidak cocok. Tanda tangani byte yang persis sama dengan yang dikirim.
401	MISSING_HMAC_SIGNATURE	Mode Enhanced HMAC aktif tetapi `X-Signature` atau `X-Timestamp` tidak dikirim.
401	TIMESTAMP_EXPIRED	`X-Timestamp` berselisih lebih dari 300 detik dari jam server. Bandingkan dengan `data.server_time`.
401	INVALID_HMAC_SIGNATURE	Tanda tangan Enhanced HMAC tidak cocok. Periksa PATH, urutan dan encode PARAMS, serta timestamp.
429	RATE_LIMIT_EXCEEDED	Batas permintaan per menit terlampaui. Tunggu `retry_after` detik.
403	MERCHANT_KYC_INCOMPLETE	Verifikasi merchant belum lengkap. `data.onboarding_url` menunjuk halaman untuk melengkapinya.
400	PAYMENT_METHOD_NOT_AVAILABLE	Kode metode tidak dikenal, atau metodenya sedang nonaktif.
403	PAYMENT_METHOD_NOT_ENABLED	Metode ada tetapi belum diaktifkan di akun Anda.
400	AMOUNT_OUT_OF_RANGE	Nominal di luar rentang metode; `data` memuat `min_amount` dan `max_amount`.
409	PAYMENT_ALREADY_EXISTS	`merchant_ref_id` ini sudah punya tagihan; `data` berisi tagihan tersebut.
409	DUPLICATE_REF_ID	Dua permintaan dengan ref yang sama tiba bersamaan dan yang ini kalah. Cek status ref tersebut.
500	PAYMENT_GATEWAY_ERROR	Mitra pembayaran menolak atau tidak menjawab. Tidak ada yang tersimpan; coba lagi dengan ref yang sama atau metode lain.
404	PAYMENT_NOT_FOUND	Tidak ada tagihan dengan `merchant_ref_id` itu di akun ini.
400	BANK_NOT_VERIFIED	Rekening penarikan belum diverifikasi di dasbor.
400	BANK_DETAILS_INCOMPLETE	Data rekening penarikan belum lengkap.
400	INSUFFICIENT_BALANCE	Saldo tersedia kurang dari `amount` ditambah biaya; `data.shortage` adalah kekurangannya.
400	PENDING_SETTLEMENT_EXISTS	Masih ada penarikan yang berjalan. Tunggu sampai selesai.
400	WITHDRAWAL_REJECTED	Penarikan ditolak karena keadaan akun berubah saat diproses. Periksa saldo dan rekening, lalu coba lagi.
503	PAYOUT_UNAVAILABLE	Layanan transfer sedang tidak bisa memproses penarikan (sisi kami, bukan saldo Anda). Coba lagi beberapa menit kemudian.
500	INTERNAL_SERVER_ERROR	Kesalahan di sisi kami; detailnya tidak dikirim. Coba lagi, atau hubungi dukungan dengan waktu kejadian dan `merchant_ref_id`.
503	SERVICE_UNAVAILABLE	Layanan sementara tidak tersedia. Coba lagi setelah `Retry-After` detik.

Bagaimana membaca galat validasi?#

Status 422 berarti satu atau lebih field tidak valid. errors memetakan nama field ke daftar pesan. Pesannya bisa berbahasa Inggris atau Indonesia, jadi catat untuk tim Anda dan jangan dijadikan logika.

422 Unprocessable Content

{
  "message": "Amount must be an integer",
  "errors": {
    "amount": [
      "Amount must be an integer"
    ]
  }
}

Galat mana yang boleh diulang?#

Status	Ulang?	Catatan
400, 401, 403, 404, 409, 422	Tidak	Perbaiki permintaan, kunci, atau konfigurasi dulu.
429	Ya	Tunggu sesuai header `Retry-After`.
503	Ya	Gangguan sementara di sisi kami. Tunggu sesuai `Retry-After`.
500 dan timeout	Hati-hati	`POST /payment`: ulang dengan `merchant_ref_id` yang sama, aman (idempotensi). `POST /withdrawal`: jangan ulang otomatis; cek saldo dan riwayat dulu.

Siap memakai kunci Anda sendiri?

Masuk ke dasbor merchant untuk mengambil API key dan secret key, mengatur mode akses dan URL webhook, serta mengunduh koleksi Postman berisi kunci akun Anda.

Masuk ke dasbor