Unified Error Catalog — Kushki ONE Connect

September 09, 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.

On payment endpoints the HTTP status is always 200, whatever happened: it confirms that the terminal processed your request, not that the operation succeeded. Always evaluate the body. The print endpoints are the exception and return real codes — 404 when the job does not exist, 409 while the queue is busy.

The five fields above sit at the root of the body. The two envelopes older builds returned, {"success": false, "data": {…}} and {"failure": {…}}, no longer exist. And object.terminal_id may arrive empty on TER-003 — do not depend on it.

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

When param is present, and when it is not

param is not an optional field that happens to be missing sometimes. It is omitted deliberately whenever the error was not caused by a field of your request. The rule in one line: param appears only when the error is attributable to a request field.

Without this rule an integrator reads the catalog, sees param among the fields, and codes assuming it always arrives.

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 2002 to 2021 range, plus the BAD_FORMAT format code.

3.1 System codes

3.2 Amount and payment field validators

3.3 Installment validators (deferred)

Installments travel in the deferred object in every market except Mexico, which uses the boolean query_deferred. The two are mutually exclusive and never travel together. These validations have no numeric code assigned yet:

The ceiling depends on the market: Mexico sends query_deferred as a boolean, Chile allows up to 12 months with credit_type: "03" or up to 48 without it, Colombia up to 48, and Peru 2 to 48 for every card network. The full contract, country by country, is in Accept payments with Kushki One.

3.4 Transaction identifier validators

3.5 Pagination and date 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: “AUTH”

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

{
  "type": "AUTH",
  "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 acquirer’s native code, unchanged and unprefixed. E020 is returned as E020. Authorization codes are native to the processing network and are left intact to preserve the ISO 8583 traceability the card brands require — do not expect an ACQ- prefix, it never arrives.
• 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": "E020",
  "message": "Either Invalid amount or Currency conversion field overflow"
}

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

{
  "type": "ACQUIRER",
  "code": "E020",
  "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: “TERMINAL-SUNMI”

Errors from the manufacturer SDK are wrapped with the MAN- prefix — a single hyphen — followed by the number. The code confirmed in real responses is MAN-30005: the card read or the PIN entry timed out, which you treat as an expected cancellation rather than a failure. For the full Sunmi catalog by functional range, ask your Kushki integration team.

{
  "type": "TERMINAL-SUNMI",
  "code": "MAN-30005",
  "message": "Input PIN timeout",
  "object": {
    "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af69",
    "terminal_id": "172653",
    "serial_number": "SN816265"
  }
}

9. Configuration errors — type: “CONFIGURATION”

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

{
  "type": "CONFIGURATION",
  "code": "CONF-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)})