Getting Started/Response Codes

Response Codes

Kuickpay uses a unified two-layer response model: an HTTP status code for transport, and a response_Code field inside the JSON body for business logic.

Standard API Response Codes

Returned in the response_Code / Response_Code field by all V3 and Hybrid endpoints.

Code	Meaning
00	Success — request processed successfully.
01	Not found — consumer number or voucher does not exist.
02	Blocked / inactive — the bill or consumer is restricted.
03	Unknown / duplicate — bad request or duplicate transaction.
04	Invalid data — wrong credentials, missing fields, or bad format.
05	Server error — internal failure; retry or contact support.
06	Already paid — the bill was already settled.

HTTP Status Codes

Returned at the transport layer, independent of the response_Code field.

Code	Meaning
200	OK — request reached the server. Check response_Code for outcome.
401	Unauthorized — X-API-KEY, IN-ID, or IP address is invalid.
404	Not Found — endpoint path is incorrect.
500	Internal Server Error — Kuickpay-side failure; retry with backoff.

Context by Integration Type

How response codes apply across different integration patterns.

End-to-End Institution

Your BillInquiry and BillPayment APIs must return Response_Code in the body. HTTP 200 is expected for all cases — use Response_Code for semantics, not HTTP status.

Bill Initiators

BillInquiryV3 and BillPaymentV3 return response_Code in the JSON body. HTTP 401 is returned when X-API-KEY or IN-ID headers are invalid.

Hybrid Institution

All insertPPMVoucher, PaymentInquiry, BulkInquiry, and GetBillers endpoints return response_Code. HTTP 401 applies when headers are missing or IP is not whitelisted.

Handling Errors — Recommended Pattern

const res = await fetch(url, { method: 'POST', headers, body });

// 1. Check HTTP layer first
if (!res.ok) {
  if (res.status === 401) throw new Error('Invalid credentials or IP not whitelisted');
  throw new Error(`HTTP ${res.status}`);
}

const data = await res.json();

// 2. Then check business response_Code
switch (data.response_Code) {
  case '00': return data;       // success
  case '01': throw new NotFoundError();
  case '02': throw new BlockedError();
  case '06': throw new AlreadyPaidError();
  default:   throw new Error(`API error: ${data.response_Code}`);
}