Error Catalog

Beta — Early Access

Kushki ONE is currently in Beta for Colombia 🇨🇴. Endpoints, parameters and response structures may change without prior notice. Do not deploy to production without coordinating with the Kushki integration team.

Kushki ONE Connect simplifies error handling with a single structured JSON model that standardizes every failure response — regardless of whether the problem originated in the terminal, a validation, authentication, or the acquirer. This lets you build more robust integrations, automate recovery flows, and stop relying solely on HTTP status codes.

This catalog is your primary diagnostic tool. It covers the error model structure, per-category code catalogs, how we map third-party rejections, and a quick-reference troubleshooting guide.

All errors share the same response structure. Always evaluate type first to classify the failure source, then look up the corresponding code.

Field	Type	Always present	Description
`type`	String	✅	Error category. Identifies the failure source. See Section 2.
`code`	String	✅	Unique error code. Prefix + number for Kushki ONE's own families (`PAR-003`, `TER-004`, `AUTH-001`, `NF-001`, `CONF-4007`, `MAN-30005`). Acquirer codes are the processor's own, unprefixed.
`param`	String	❌	The exact request field that caused the error. Present only when the failure is attributable to a field — see below.
`message`	String	✅	Human-readable description of the failure reason.
`object`	Object	❌	Traceability data: `client_transaction_id`, `terminal_id` and `serial_number`.

Canonical example:

{
  "type": "PARAMETER",
  "code": "PAR-003",
  "param": "amount.iva",
  "message": "Field amount.iva must satisfy: value >= 0",
  "object": {
    "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af69",
    "terminal_id": "172653",
    "serial_number": "TJ54241R20931"
  }
}

The response is flat — there is no wrapper

The five fields above sit at the root of the body. The two envelopes that older builds returned, {"success": false, "data": {…}} and {"failure": {…}}, no longer exist. If your POS parses either of them it will stop finding the error. Read type and code from the root.

INFO

object.terminal_id may arrive empty on TER-003. It is a known gap; do not make your error handling depend on it being populated.

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.

Comes with `param`	Why
`PAR-003`, `TER-003`, `AUTH-001`	Data validation errors — there is a field at fault
`NF-001`	Carries the identifier that was not found

Comes without `param`	Why
`TER-004`	Printer busy, or the cardholder cancelled. The request was valid; the hardware or the person was not
`MAN-30005`	Card or PIN timeout. Same reason
`ACQUIRER`	The transaction was valid and the bank declined it
`CONF-4007`	Terminal provisioning, not the call
`PAR-002` with unreadable JSON	The parser fails before deserializing, so there is no field to point at

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

The HTTP status does not tell you the outcome

DANGER

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 response body.

A POS that branches on response.ok treats a busy terminal, an expired PIN and a cardholder cancellation as successes. Verified in testing, all with 200: a negative parameter, a busy terminal and a PIN timeout on /sync/charge; an offline decline and a user cancellation on /async/authorization; an operation not allowed and an invalid parameter on /async/capture; and an amount larger than the sale on /async/void.

The print endpoints are the exception and do return real HTTP codes: 404 when the job does not exist, 409 while the queue is busy.

2. Error categories (`type` field)

`type`	Origin	Description
`PARAMETER`	Validation	Incorrect field submission: empty required fields, wrong type, or invalid format.
`TERMINAL`	Terminal	Physical terminal cannot accept the requested operation: busy, offline, not linked, incompatible mode.
`AUTH`	Security	Unable to authenticate the caller, or insufficient permissions to execute the action.
`NOT_FOUND`	Routing	Service or endpoint not found. Invalid URL.
`ACQUIRER`	Acquirer	Errors related to transaction processing or authorization by the Kushki acquirer.
`INTERNAL`	Application	Unexpected errors: services down, internal application errors, and Cloud relay failures.
`CONFIGURATION`	Terminal capability	The requested operation is not enabled, or exceeds the limits configured for this terminal.
`TERMINAL-PRINTER`	Hardware	Errors from the integrated thermal printer (no paper, cover open, paper jam, etc.).
`TERMINAL-SUNMI`	Hardware SDK	Errors from the manufacturer SDK. Code prefixed `MAN-`.

3. Validation errors — `type: "PARAMETER"`

Generated when the request contains fields with incorrect format, out-of-range values, or missing required fields. The param field identifies the specific field that caused the error. All PARAMETER errors are 100% preventable by validating the payload before calling the API.

`code`	Description	Message template	Example
`PAR-001`	Required field not sent.	`Field {{field}} is required.`	`Field amount.subtotal_iva0 is required.`
`PAR-002`	Field of incorrect type, or body that is not valid JSON.	`Field {{field}} must be a/an {{type}}`	`Field amount.subtotal_iva must be an integer.`
`PAR-003`	Field with incorrect format or invalid value.	`Field {{field}} must satisfy: {{condition}}`	`Field amount.iva must satisfy: value >= 0.`

3.1 System format codes

`code`	Description
`BAD_FORMAT`	JSON/JVM parse error. The request body is not valid JSON, or contains an incorrect data type in a field.

INFO

There is no BUSY code. A busy terminal is TER-003 when it is running a transaction and TER-004 when it is printing — both with type: TERMINAL. See Section 4.

3.2 Amount and payment field validators

param uses the same snake_case and the same full path as your request, so the value you read is the exact name to search for in your own payload.

Code	`param`	Error message	Applies to
`2002`	`amount.iva`	`amount.iva cannot be negative`	All
`2003`	`amount.subtotal_iva`	`amount.subtotal_iva cannot be negative`	All
`2004`	`amount.subtotal_iva0`	`amount.subtotal_iva0 cannot be negative`	All
`2005`	`amount.tip`	`amount.tip cannot be negative`	`/charge` and `/authorization`
`2006`	`amount.extra_taxes.airport_tax`	`amount.extra_taxes.airport_tax cannot be negative`	All
`2007`	`amount.extra_taxes.iac`	`amount.extra_taxes.iac cannot be negative`	All
`2008`	`amount.extra_taxes.ice`	`amount.extra_taxes.ice cannot be negative`	All
`2009`	`amount.extra_taxes.travel_agency`	`amount.extra_taxes.travel_agency cannot be negative`	All

INFO

On /pos_tip, amount.tip is not an optional field — it is the amount of the operation, so 2005 applies there too. The full map of which optional field belongs to which operation is in Cloud Services.

3.3 Installment validators (`deferred`)

In Colombia installments travel in the deferred object. These validations have no numeric code assigned yet:

Condition	Result
`deferred.months` above 48	`PARAMETER` error on `deferred.months`
`deferred.credit_type` sent from Colombia	`PARAMETER` error — `credit_type` exists only in Chile
`deferred` and `query_deferred` sent together	`PARAMETER` error — the two are mutually exclusive, and `query_deferred` is Mexico only

3.4 Transaction identifier validators

Code	`param`	Error message
`2010`	`client_transaction_id`	`client_transaction_id must be a valid UUID format`
`2011`	`client_transaction_id`	`client_transaction_id is required`
`2014`	`transaction_reference`	`transaction_reference must be a valid UUID format`
`2015`	`transaction_reference`	`transaction_reference is required`

3.5 Pagination and date validators

Code	`param`	Error message
`2016`	`page`	`page must be greater than 0`
`2017`	`size`	`size must be greater than 0`
`2018`	`size`	`size must not exceed 500`
`2019`	`start_date`	`start_date cannot be negative`
`2020`	`end_date`	`end_date cannot be negative`
`2021`	`start_date`	`start_date must be before end_date`

INFO

Date filters in transaction search are Unix timestamps in milliseconds, interpreted in the terminal's local time — America/Bogota for Colombia. A 10-digit value in seconds is not rejected: it lands in 1970 and the search silently returns your whole history. See Transaction Search.

4. Terminal errors — `type: "TERMINAL"`

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

`code`	Description	Message template	Example
`TER-001`	Terminal not linked to the merchant.	`Terminal {{serial_number}} does not exist, or is not linked to your account.`	`Terminal SN816265 does not exist, or is not linked to your account.`
`TER-002`	Terminal not responding (offline or off-network).	`Terminal {{serial_number}} is not responding. It may be offline or not connected to the local network.`	`Terminal PB651542 is not responding. It may be offline or not connected to the local network.`
`TER-003`	Terminal busy processing a transaction.	`Terminal {{serial_number}} is busy processing transaction (client_transaction_id: {{id}}).`	`Terminal SN71652 is busy processing transaction (client_transaction_id: c5a3f3be-9d6f-4d39-8af5-58dbb589af69).`
`TER-004`	Printer busy, or cardholder cancellation. See below.	`Terminal {{serial_number}} is busy executing action {{action}}.`	`Terminal JH152353 is busy executing action PRINT.`
`TER-005`	Terminal in a mode incompatible with the operation.	`The terminal is in {{mode}} mode and does not allow the requested action.`	`The terminal is in STANDALONE mode and does not allow the requested action.`
`TER-006`	Terminal not enabled for that operation type.	`The terminal is not allowed to process {{type}}.`	`The terminal is not allowed to process TIP.`

`TER-004` means two different things

The endpoint you called tells you which one, so you never have to disambiguate at runtime:

Where you got it	What it means	What to do
`/print` or `/print_job`	The printer is busy; the `message` names the action in progress	Retry in a few seconds
Any payment endpoint	The cardholder cancelled on the terminal screen	Do not retry — it is an expected cancellation

INFO

The terminal handles one transaction at a time. TER-003 and TER-004 are the expected answer when your POS sends a second command before the first completes — wait, or call abort.

5. Authentication errors — `type: "AUTH"`

Generated when credentials are invalid or lack sufficient permissions to execute the requested action.

`code`	Description	Message
`AUTH-001`	Credentials cannot be authenticated.	`Invalid or expired credentials`
`AUTH-002`	Credentials are valid but lack permission for the action.	`Your credentials are valid but do not grant access to this resource.`

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

The four common causes of AUTH-001:

The body was re-serialized after signing, so the hash no longer matches the bytes sent.

The timestamp falls outside the ±5 minute window around server time.

Signing with the private_credential_id instead of the Business-Code. private_credential_id is a terminal configuration value and is never used to sign requests.

On an operation with no payload — /abort — signing an empty string instead of the literal {}. Two bytes of difference, and no hint in the response.

Security

Never log the full value of the Authorization header in production. Only log its presence or absence for diagnostic purposes.

6. Routing and internal errors

`type: "NOT_FOUND"`

`code`	Description	Message template	Example
`NF-001`	Service or endpoint not found.	`Service not found: {{url}}`	`Service not found: https://cloudt.kushkipagos.com/cobrar`

`type: "INTERNAL"`

`code`	Description	Message
`INT-001`	Unexpected server or application error.	`Internal server error.`
`MQTT_REQUEST_FAILED`	The Cloud relay could not deliver the command to the terminal. Cloud only — it does not occur on the local network.	`MQTT request failed`

7. Acquirer errors — `type: "ACQUIRER"`

Errors originating from the Kushki acquirer are encapsulated under type: "ACQUIRER" using the following mapping rule.

Mapping rule

code: the acquirer's native code, unchanged and unprefixed. E020 is returned as E020.

message: same message originally returned by Kushki.

object: includes client_transaction_id, terminal_id and serial_number when applicable.

Why there is no prefix

Authorization codes are native to the processing network and are left intact on purpose, to preserve the ISO 8583 traceability the card brands require. Do not expect an ACQ- prefix — it never arrives.

Mapping example

Original Kushki error:

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

Mapped response from Kushki ONE Connect:

{
  "type": "ACQUIRER",
  "code": "E020",
  "message": "Either Invalid amount or Currency conversion field overflow",
  "object": {
    "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af69",
    "terminal_id": "172653",
    "serial_number": "PJ715652"
  }
}

INFO

An amount rejection in a COP market is very often a minor-unit mistake rather than a real acquirer problem — check the amount against Building the amount before escalating.

8. Manufacturer errors — `type: "TERMINAL-SUNMI"`

Errors from the manufacturer SDK are encapsulated under type: "TERMINAL-SUNMI" with a code in the MAN- family, a single hyphen.

Mapping rule

code: MAN- followed by the number. Example: MAN-30005.

message: original message from the manufacturer SDK.

object: includes client_transaction_id, terminal_id and serial_number when applicable.

`code`	Description	Recommended action
`MAN-30005`	Card read or PIN entry timed out.	The cardholder did not present the card or did not enter the PIN in time. Request a retry; treat it as an expected cancellation, not a failure.

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

INFO

Manufacturer SDK codes are read-only and intended for diagnostics and logging. For the complete Sunmi code catalog by functional range (card reading, cryptography, EMV, PIN, Android permissions), ask your Kushki integration team.

9. Configuration errors — `type: "CONFIGURATION"`

Generated when the requested operation is not enabled for this terminal, or when the amount sent exceeds a configured limit. Unlike PARAMETER errors these are not fixed by modifying the payload — they need a capability or a limit changed for your terminal.

`code`	Cause	Recommended action
`CONF-4001`	Tip is not enabled for this terminal.	Request tip to be enabled at soporte@kushkipagos.com.
`CONF-4002`	Cashback is not enabled for this terminal.	Request cashback to be enabled at soporte@kushkipagos.com.
`CONF-4003`	Cashback amount exceeds the configured maximum.	Inform the customer of the available limit. Do not retry with the same amount. To raise the limit, write to soporte@kushkipagos.com.
`CONF-4006`	Transaction amount exceeds the configured maximum for this payment type.	Inform the customer. To raise the limit, write to soporte@kushkipagos.com.
`CONF-4007`	Terminal provisioning problem — not caused by your call.	Escalate to soporte@kushkipagos.com with the `serial_number`.

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

INFO

These errors are not resolved in code. A CONFIGURATION error means the feature exists but is not active for this terminal. Note that when a capability is simply absent the terminal may instead ignore the field rather than reject the call, so do not rely on a tip being applied without checking the response.

10. Printer errors — `type: "TERMINAL-PRINTER"`

Errors generated by the integrated thermal printer hardware. These codes are standardized regardless of the terminal manufacturer, and they also arrive on the print webhook as errorCode.

`code`	Cause	Recommended action for the operator
`OUT_OF_PAPER`	No paper roll loaded.	Insert a new roll and retry.
`COVER_OPEN`	Paper compartment cover is open.	Close the cover firmly.
`COVER_INCOMPLETE`	Cover improperly closed, or roller not applying pressure.	Open and close again, ensuring the roller latches correctly.
`PAPER_JAM`	Paper jammed in the mechanism.	Remove the jammed paper and close. Insert a new roll.
`PRINTER_HOT`	Thermal printhead overheated.	Wait 2–3 minutes and retry.
`MOTOR_HOT`	Feed motor overheated.	Wait for cool-down.
`CUTTER_ERROR`	Auto-cutter blade jammed.	Requires technical service intervention.
`OFFLINE`	Module not responding to the Android system.	Restart the terminal.

INFO

A busy print queue is not in this table: it arrives as TER-004 with type: TERMINAL, and over HTTP as a 409.

11. Quick diagnostic guide

When you receive an error, follow these recommendations:

On a payment endpoint, did you get 200? → That means nothing about the outcome. Read the body before deciding.

type is AUTH? → Verify credentials (AUTH-001) or permissions (AUTH-002). Check the four causes in Section 5: re-serialized body, clock outside ±5 min, signing with the wrong key, or an empty string instead of {}.

type is PARAMETER? → Review the field indicated in param. Add validation in the POS before calling the API. If param is absent, the body was not readable as JSON.

type is TERMINAL, code is TER-002? → Terminal is offline. Check network connectivity.

type is TERMINAL, code is TER-003? → Terminal is busy with a transaction. Wait, or use abort.

type is TERMINAL, code is TER-004? → On a print endpoint, the printer is busy: retry. On a payment endpoint, the cardholder cancelled: do not retry.

type is TERMINAL, code is TER-006? → Capability not enabled for this terminal. Write to soporte@kushkipagos.com.

type is TERMINAL-PRINTER? → Physical hardware condition. Show the message to the operator with resolution instructions.

type is TERMINAL-SUNMI, code is MAN-30005? → Card or PIN timeout. Treat as an expected cancellation.

type is ACQUIRER? → Processor rejection. Show the message to the customer. Log the native code with the client_transaction_id for support.

type is INTERNAL, code is MQTT_REQUEST_FAILED? → The Cloud relay could not reach the terminal. Check the terminal is online and retry; if it persists, escalate.

type is INTERNAL or NOT_FOUND? → Log the full payload and escalate to Kushki technical support.

type is CONFIGURATION? → Capability not enabled, or amount over a configured limit. Do not retry with the same payload. Write to soporte@kushkipagos.com.

INFO

Best practice: always log type + code + message + object.client_transaction_id + timestamp in your logging system. This information is essential for fast diagnosis.

Errors delivered on the webhook

On an async operation, a failure does not arrive as an HTTP error — it arrives as an event. TERMINAL_REJECTED and DECLINED carry a failure_reason object with the same type, code and message documented above:

{
  "status": "TERMINAL_REJECTED",
  "previous_status": "CARD_PRESENTED",
  "failure_reason": {
    "type": "TERMINAL-SUNMI",
    "code": "MAN-30005",
    "message": "Input PIN timeout"
  }
}

Resolve failure_reason.code against this catalog exactly as you would an HTTP error body. See Webhooks.

Webhooks

Where failure_reason arrives, and how to build an idempotent consumer.

Transaction Examples

Copy-ready requests, and the amount conversion rules for COP.

Got a suggestion on this documentation? Contact us.

When param is present, and when it is not#

The HTTP status does not tell you the outcome#

2. Error categories (type field)#

3. Validation errors — type: "PARAMETER"#

3.1 System format codes#

3.2 Amount and payment field validators#

3.3 Installment validators (deferred)#

3.4 Transaction identifier validators#

3.5 Pagination and date validators#

4. Terminal errors — type: "TERMINAL"#

TER-004 means two different things#

5. Authentication errors — type: "AUTH"#

6. Routing and internal errors#

type: "NOT_FOUND"#

type: "INTERNAL"#

7. Acquirer errors — type: "ACQUIRER"#

Mapping rule#

Mapping example#

8. Manufacturer errors — type: "TERMINAL-SUNMI"#

Mapping rule#

9. Configuration errors — type: "CONFIGURATION"#

10. Printer errors — type: "TERMINAL-PRINTER"#

11. Quick diagnostic guide#

Errors delivered on the webhook#

Related#

When `param` is present, and when it is not

The HTTP status does not tell you the outcome

2. Error categories (`type` field)

3. Validation errors — `type: "PARAMETER"`

3.1 System format codes

3.2 Amount and payment field validators

3.3 Installment validators (`deferred`)

3.4 Transaction identifier validators

3.5 Pagination and date validators

4. Terminal errors — `type: "TERMINAL"`

`TER-004` means two different things

5. Authentication errors — `type: "AUTH"`

6. Routing and internal errors

`type: "NOT_FOUND"`

`type: "INTERNAL"`

7. Acquirer errors — `type: "ACQUIRER"`

Mapping rule

Mapping example

8. Manufacturer errors — `type: "TERMINAL-SUNMI"`

Mapping rule

9. Configuration errors — `type: "CONFIGURATION"`

10. Printer errors — `type: "TERMINAL-PRINTER"`

11. Quick diagnostic guide

Errors delivered on the webhook

Related