Unified Error Catalog — Kushki ONE Connect

August 04, 2026

Kushki ONE Connect returns a structured JSON payload on any failure, whether the problem started at the terminal, in a validation, in authentication or at the acquirer. That lets you build robust integrations, automate recovery flows and stop depending solely on HTTP status codes.

This manual is your diagnostic tool: the data model structure, the catalogs by category, how we map third-party rejections and a quick guide for the common cases.

1. Error models

There are two error envelopes. Which one you get depends on whether the failure arrives in an HTTP response or in an async event.

1.1 HTTP responses: LinkFailure

Every error response shares this structure. Evaluate the type field first to classify the source of the failure, then look up the matching code.

The HTTP status code is consistent with the type in the body. For ACQUIRER errors we keep the status Kushki originally returned.

{
  "type": "PARAMETER",
  "code": "PAR-003",
  "param": "amount",
  "message": "Amount must be a value greater than 0",
  "object": {
    "client_transaction_id": "1018282",
    "terminal_id": "172653",
    "serial_number": "PJ715652"
  }
}

1.2 Async events: failure_reason

When you integrate over async mode, failures do not arrive in an HTTP response but inside the webhook event, in the failure_reason object.

{
  "status": "TERMINAL_REJECTED",
  "previous_status": "CARD_PRESENTED",
  "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79",
  "failure_reason": {
    "type": "TERMINAL",
    "code": "TER-172",
    "message": "The maximum operation time was exceeded."
  }
}

2. Error categories

3. Validation errors — type: “PARAMETER”

These are generated when the request contains fields with the wrong format, values out of range or missing required fields. The param field identifies the specific field. All of them are preventable by validating the payload in your POS system before you call the API.

When type is PARAMETER, the code can also be a numeric code in the 2001 to 2037 range, plus two special format codes.

3.1 System codes

3.2 Amount and payment field validators

3.3 Transaction identifier validators

3.4 Pagination and date validators

3.5 Configuration validators

4. Terminal errors — type: “TERMINAL”

These are generated when the physical terminal cannot accept the operation. Unlike hardware errors, they point to a state or connectivity problem, not a component failure.

5. Authentication errors — type: “AUTHENTICATION”

These are generated when credentials are invalid or do not carry enough permissions for the requested action.

{
  "type": "AUTHENTICATION",
  "code": "AUTH-001",
  "message": "Invalid or expired credentials"
}

6. Routing and internal errors

type: “NOT_FOUND”

type: “INTERNAL”

7. Acquirer errors — type: “ACQUIRER”

Errors from the Kushki acquirer are wrapped under type: "ACQUIRER" with this mapping rule:

• code: the original Kushki code with the ACQ- prefix. Code 13 becomes ACQ-13.
• message: identical to Kushki’s original message.
• object: includes client_transaction_id, terminal_id and serial_number where applicable.
• HTTP status: we keep the one Kushki originally returned.

Original Kushki error:

{
  "code": "13",
  "message": "Either Invalid amount or Currency conversion field overflow"
}

Error mapped by Kushki ONE Connect, with the same 400 Bad Request:

{
  "type": "ACQUIRER",
  "code": "ACQ-13",
  "param": "",
  "message": "Either Invalid amount or Currency conversion field overflow",
  "object": {
    "client_transaction_id": "1018282",
    "terminal_id": "172653",
    "serial_number": "PJ715652"
  }
}

8. Manufacturer errors — type: “MANUFACTURER”

Errors from the manufacturer SDK are wrapped with the MAN- prefix followed by the original code. Sunmi’s -2001 becomes MAN--2001.

{
  "type": "MANUFACTURER",
  "code": "MAN--2001",
  "message": "Have no card",
  "object": {
    "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af69",
    "terminal_id": "172653",
    "serial_number": "SN816265"
  }
}

Most frequent Sunmi codes

9. Configuration errors — type: “CONFIGURATION”

These are generated when the operation is not enabled for that terminal in the DMS, or when the amount exceeds the configured limits. Unlike PARAMETER errors, they are not fixed by changing the payload.

{
  "type": "CONFIGURATION",
  "code": "-4001",
  "message": "Tip is not enabled",
  "object": {
    "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af69",
    "terminal_id": "172653",
    "serial_number": "SN816265"
  }
}

10. Kushki Printer errors — type: “TERMINAL-PRINTER”

Errors from the printing hardware. They are standardized regardless of the terminal manufacturer.

11. Quick diagnostic guide

To debug a signature failure, this is the minimum logging pattern:

try {
  const res  = await fetch(url, { method: "POST", headers, body });
  const data = await res.json();

  if (!res.ok) {
    logger.error("kushki_one_error", {
      http: res.status,
      type: data.type,
      code: data.code,
      transaction: data.object?.client_transaction_id,
      signaturePresent: Boolean(headers.Authorization),
    });
  }
} catch (e) {
  logger.error("kushki_one_network", { message: e.message });
}

try:
    res  = requests.post(url, headers=headers, json=payload, timeout=30)
    data = res.json()

    if not res.ok:
        logger.error("kushki_one_error", extra={
            "http": res.status_code,
            "type": data.get("type"),
            "code": data.get("code"),
            "transaction": data.get("object", {}).get("client_transaction_id"),
            "signature_present": "Authorization" in headers,
        })
except requests.RequestException as e:
    logger.error("kushki_one_network", extra={"message": str(e)})