Kushki ONE is currently in Beta for Peru 🇵🇪. 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.
The exact field or parameter that caused the error. Used primarily in PARAMETER errors.
message
String
✅
Human-readable description of the failure reason.
object
Object
❌
Traceability data. Includes client_transaction_id, terminal_id and serial_number when applicable.
INFO
HTTP status code: the HTTP status is consistent with the type in the body. For ACQUIRER errors, the original HTTP status 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":"c5a3f3be-9d6f-4d39-8af5-58dbb589af69","terminal_id":"172653","serial_number":"PJ715652"}}
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.
deferredMonths must be > 0 when isDeferred is true
All
2013
cashbackAmount
cashbackAmount must be > 0 when isCashback is true
pos_tip and /async/charge
tip and cashback_amount are not accepted everywhere
amount.tip (code 2005) and cashback_amount (code 2013) are accepted by pos_tip and by /async/charge only. The sync charge and both variants of authorization do not carry them — sending them there is a validation error. Tip and cashback additionally require the matching capability enabled in DMS; see Section 9.
INFO
The currency in Peru is PEN. It is not sent in the payload — it comes from the terminal's DMS configuration, so a 2001 means the terminal is configured for a different market than the one you are integrating.
These are DMS configuration fields, validated when a terminal is provisioned. privateCredentialId is a terminal configuration value — it is never used to sign requests. The signing key is the Business-Code.
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
Terminal busy with a non-payment action.
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.
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.
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":"AUTHENTICATION","code":"AUTH-001","message":"Invalid or expired credentials"}
The most common causes of AUTH-001 are a body re-serialized after signing, a timestamp outside the ±5 minute window, and signing with the private_credential_id instead of the Business-Code. See Required headers.
Security
Never log the full value of the Authorization header in production. Only log its presence or absence for diagnostic purposes.
HTTP/1.1 400 Bad Request
{
"code": "13",
"message": "Either Invalid amount or Currency conversion field overflow"
}
Mapped response from Kushki ONE Connect:
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": "c5a3f3be-9d6f-4d39-8af5-58dbb589af69",
"terminal_id": "172653",
"serial_number": "PJ715652"
}
}
INFO
ACQ-13 in a PEN market is very often a minor-unit mistake rather than a real acquirer problem — check the amount against Building the amount before escalating.
Errors from the manufacturer SDK (Sunmi, Landi) are encapsulated under type: "MANUFACTURER" with code MAN-{manufacturer_code}. Sunmi SDK codes are negative, so the resulting code carries two hyphens.
message: original message from the manufacturer SDK.
object: includes client_transaction_id, terminal_id and serial_number when applicable.
{"type":"MANUFACTURER","code":"MAN--2001","message":"Have no card","object":{"client_transaction_id":"c5a3f3be-9d6f-4d39-8af5-58dbb589af69","terminal_id":"172653","serial_number":"SN816265"}}
INFO
Sunmi SDK codes are read-only. They are intended for diagnostic and logging purposes only.
Customer canceled PIN entry. Handle as cancellation.
MAN--60001
Input PIN timeout
Customer did not enter PIN in time. Request retry.
INFO
For the complete Sunmi code catalog by functional range (card reading, cryptography, EMV, PIN, Android permissions), ask your Kushki integration team for the full Sunmi Error Catalog.
Generated when the requested operation is not enabled for this terminal in DMS, or when the sent amount exceeds configured limits. Unlike PARAMETER errors, these are not fixed by modifying the payload — they require a configuration change by the Kushki Operations team.
code
Cause
Recommended action
-4001
Tip is not enabled in the terminal configuration.
Contact Kushki Operations to enable tip functionality in DMS.
-4002
Cashback is not enabled in the terminal configuration.
Contact Kushki Operations to enable cashback functionality in DMS.
-4003
Cashback amount exceeds the configured maximum limit.
Inform the customer of the available limit. Do not retry with the same amount.
-4006
Transaction amount exceeds the configured maximum for this payment type.
Inform the customer. Contact Kushki Operations if the limit needs adjustment.
{"type":"CONFIGURATION","code":"-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. The fix always goes through DMS — not through modifying the request. Note that when a capability is simply absent the terminal may also ignore the field rather than reject the call, so do not rely on a tip being applied without checking the response.
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.
When you receive an error, follow these recommendations:
type is AUTHENTICATION? → Verify credentials (AUTH-001) or permissions (AUTH-002). Check that you signed with the Business-Code and did not re-serialize the body.
type is PARAMETER? → Review the field indicated in param. Add validation in the POS before calling the API.
type is PARAMETER, code is 2001? → The terminal is configured for a currency other than PEN. Escalate to Kushki Operations; this is not fixable from the payload.
type is TERMINAL, code is TER-002? → Terminal is offline. Check network connectivity.
type is TERMINAL, code is TER-003 or TER-004? → Terminal is busy. Wait for the current operation to finish, or use abort.
type is TERMINAL, code is TER-006? → Feature not enabled on this terminal. Contact Kushki Operations.
type is TERMINAL-PRINTER? → Physical hardware condition. Show the message to the operator with resolution instructions.
type is MANUFACTURER, code starts with MAN--200? → Card read problem. Ask the customer to retry.
type is MANUFACTURER, code is MAN--50020 or MAN--60001? → Customer canceled or did not enter PIN. Treat as an expected cancellation.
type is ACQUIRER? → Processor rejection. Show the message to the customer. Log the code (e.g. ACQ-13) with the client_transaction_id for support.
type is INTERNAL or NOT_FOUND? → Log the full payload and escalate to Kushki technical support.
type is CONFIGURATION? → Feature not enabled, or amount exceeds a configured limit. Do not retry with the same payload. Contact Kushki Operations to adjust the DMS configuration.
INFO
Best practice: always log type + code + message + object.client_transaction_id + timestamp in your logging system. This information is essential for fast diagnosis.
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:
