Unified Error Catalog — Kushki ONE Connect

April 01, 2026

We simplify error management in Kushki ONE Connect. In the event of any operation failure, our API returns a structured payload in JSON format (LinkFailure) that standardizes the response regardless of whether the problem originated at the terminal, in validation, in authentication, or at the acquirer. This allows you to build more robust integrations, automate recovery flows, and stop relying exclusively on HTTP Status Codes.

This manual is your primary diagnostic tool. It details the structure of the new data model, the code catalogs by category, how we map third-party rejections, and a quick guide to resolving common problems.

1. Error Models

All errors share the same response structure. The type field should be evaluated first to classify the source of the failure, and then the corresponding code should be consulted.

HTTP Status Code

The HTTP status code is consistent with the body’s type. For ACQUIRER errors, the same HTTP status originally returned by Kushki is preserved.

Canonical example

{
"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"
}
}

2. Error Categories (type field)

3. Validation Errors — type: “PARAMETER”

Generated when the sent request contains incorrectly formatted fields, values out of range, or missing required fields. The param field identifies the specific field that caused the error. All are 100% preventable by validating the payload before calling the API.

3.1 Request Validation Errors - type: “PARAMETER”

When the type is PARAMETER, the code field is always a positive numeric code in the 2001–2037 range. All are preventable by validating the payload in the checkout system before calling the API. There are also two special system format codes.

3.2 System Codes

3.3 Amount and Payment Field Validators (2001–2013)

3.4 Transaction Identifier Validators (2010–2015)

3.5 Pagination and Date Validators (2016-2021)

3.6 Configuration Validators (2022-2037)

4. Terminal Errors — type: “TERMINAL”

Generated when the physical terminal cannot accept the requested operation. Unlike hardware errors, these indicate a status or connectivity issue with the terminal, not a component failure.

5. Authentication Errors — type: “AUTHENTICATION”

Generated when credentials are invalid or do not have sufficient permissions to execute 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 originated by the Kushki acquirer are encapsulated under type: ACQUIRER applying the following mapping rule.

Mapping Rule

• code: Original Kushki code with prefix ”ACQ-”. Example: code ”13” → ACQ-13.
• message: Same as the original message returned by Kushki.
• object: Includes at least the following fields when applicable.
  • Client_transaction_id
  • terminal_id
  • serial_number
• HTTP status: The same HTTP status originally returned by Kushki is preserved.

Mapping Example

Original Kushki error:

HTTP/1.1 400 Bad Request
{
"code": "13",
"message": "Either Invalid amount or Currency conversion field overflow"
}

Mapped error — Kushki ONE Connect response:

HTTP/1.1 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”

Manufacturer SDK errors (Sunmi, Landi) are encapsulated under type: “MANUFACTURER” with code MAN-{manufacturer_code}. Negative codes from the Sunmi SDK are documented exactly as returned by the SDK.

Mapping Rule

• code: Manufacturer SDK code with prefix ”MAN-”. Example: code ”-2001” → MAN—2001.
• message: Original message from the manufacturer SDK.
• object: Includes the following fields when applicable.
  • Client_transaction_id
  • terminal_id
  • serial_number

{
"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 in production

9. Configuration Errors — type: “CONFIGURATION”

Generated when the requested operation is not enabled for this terminal in the DMS, or when the submitted amount exceeds the configured limits. Unlike PARAMETER errors, these cannot be fixed by modifying the request payload — they require a configuration change on the terminal by the Kushki Operations team.

{
  "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. Quick Diagnostic Guide

When an error is received, follow these recommendations:

• Is type AUTHENTICATION? → Verify credentials (AUTH-001) or permissions (AUTH-002).
• Is type PARAMETER? → Check the field indicated in param. Add validation in the POS before calling the API.
• Is type TERMINAL and code TER-002? → The terminal is offline. Verify network connectivity.
• Is type TERMINAL and code TER-003 or TER-004? → The terminal is busy. Wait for the current operation to finish or use abort.
• Is type TERMINAL and code TER-006? → Functionality not enabled on the terminal. Contact Kushki Operations to enable.
• Is type DEVICE? → Physical hardware condition. Show the message to the operator with resolution instructions.
• Is type MANUFACTURER and code starts with MAN—200? → Card reading problem. Request retry from the customer.
• Is type MANUFACTURER and code is MAN—50020 or MAN—60001? → The customer canceled or did not enter the PIN. Treat as an expected cancellation.
• Is type ACQUIRER? → Processor rejection. Show the message to the customer. Log the code (e.g., ACQ-13) with the client_transaction_id for support.
• Is type INTERNAL or NOT_FOUND? → Log the full payload and escalate to Kushki technical support.
• type is CONFIGURATION? → The feature is not enabled on the terminal or the amount exceeds the configured limit. Do not retry with the same payload. Contact Kushki Operations to adjust the configuration in the DMS.