SDK Error Codes

This reference covers com.koard:koard-android-sdk:1.0.7, published on Maven Central. The release AAR matches the artifact distributed in the public Android repository. For device recovery steps, see Troubleshooting.

Reading an SDK Error

Catch com.koardlabs.merchant.sdk.domain.exception.KoardException and inspect its error, a com.koardlabs.merchant.sdk.domain.KoardError:

Read errorCode only after matching error.errorType as KoardErrorType.KoardServiceErrorType.HttpError.

There is no general numeric code property on KoardError or KoardException. The reader codes below describe diagnostic conditions handled by the released SDK. They are not fields you can read back from every exception. Use the Koard type for control flow and keep a fallback for unmapped codes (GeneralError). Wrapped reader errors use Koard descriptions; their messages do not necessarily retain the numeric code or raw engine detail.

Thrown Errors, Result Failures, and Reader Events

The Activity-based tap refund returns a Flow, while the reference-based refund returns Result<KoardTransaction>. A returned value or OnComplete event does not by itself establish payment success. Use the complete Running Payments handler for transaction status, partial approvals, surcharge decisions, and recovery when no terminal event arrives.

KoardErrorType Reference

KoardErrorType is a sealed hierarchy. The following tables list Koard-facing types your app can handle directly in the published 1.0.7 AAR. Additional reader conditions are described by their diagnostic codes below; use a fallback handler for other wrapped errors. Names in each table are relative to KoardErrorType or the nested family named in the heading. Keep a fallback branch for future types and unexpected exceptions.

Top-Level Error Types

NotReady: Blocked Before the Tap Starts

sale(), preauth(), completePartialAuth(), and refundEmv() refresh their readiness checks first and throw a KoardException whose error.errorType is a KoardErrorType.NotReady.* value if the SDK cannot transact. The Flow is never returned, so wrap both the call and collection in try / catch. KoardSdkReadiness.notReadyReason() returns the same typed reason without attempting a transaction.

KoardServiceErrorType: API / HTTP Errors

Inspect KoardErrorType.KoardServiceErrorType on API failures. Methods returning Result can carry the exception as a failure; use getOrThrow() inside your try block to handle it in the same way as thrown exceptions.

HTTP responses are commonly wrapped as HttpError(errorCode), including HTTP 401 and 404. Handle those codes explicitly; do not assume they always become the separate Unauthorized or NotFound objects.

DeviceIntegrityError: Security Checks

Thrown when the device fails security validation during enrollment or transaction preparation:

TransactionErrorType: Card & Payment Errors

These public KoardErrorType.TransactionErrorType values classify transaction and validation failures. They have no public numeric-code property. They are distinct from KoardTransactionResponse.statusCode, reader display-message IDs, and HTTP status codes.

Reader Error Codes

These tables describe reader diagnostics using numeric codes when available on KoardTransactionResponse.statusCode. A wrapped exception does not necessarily retain a numeric code; handle it through KoardException.error and your fallback path. The category headings below are descriptions, not additional SDK class names.

Reader Communication

Reader Environment

Device Eligibility

Enrollment and Initialization

Reader Preparation

Generic and Unmapped Codes

A code of -1 indicates a generic eligibility, initialization/enrollment, or device-integrity failure. The SDK uses the detail available when wrapping the failure to classify it. Retain the wrapped error and a redacted description; do not assume every -1 has the same cause.

An unrecognized or unavailable underlying code maps to GeneralError. An unrecognized numeric code may appear in shortMessage, but it is not a typed numeric property. Keep a generic recovery path and retain redacted context for support.

Handling Errors in Code

This example enrolls the device without initiating a payment. Call it from your UI scope and supply the showMessage callback. It catches both the SDK invocation and its exceptions, preserves cancellation, and dispatches UI work to Main.

import com.koardlabs.merchant.sdk.KoardMerchantSdk
import com.koardlabs.merchant.sdk.domain.KoardErrorType
import com.koardlabs.merchant.sdk.domain.exception.KoardException
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext

suspend fun enrollReader(
    sdk: KoardMerchantSdk,
    showMessage: (String) -> Unit
) {
    try {
        // Authenticate and select an active location before calling this helper.
        val enrollmentMessage = withContext(Dispatchers.IO) {
            sdk.enrollDevice()
        }
        withContext(Dispatchers.Main) { showMessage(enrollmentMessage) }
    } catch (canceled: CancellationException) {
        throw canceled
    } catch (error: KoardException) {
        val message = when (val type = error.error.errorType) {
            is KoardErrorType.KoardServiceErrorType.HttpError -> when (type.errorCode) {
                401, 403 -> "Sign in and verify merchant access."
                429 -> "Too many requests. Wait before trying again."
                else -> "The request failed (HTTP ${type.errorCode})."
            }
            KoardErrorType.KoardServiceErrorType.ConnectionError ->
                "Check connectivity and enrollment state before trying again."
            KoardErrorType.NotReady.NoActiveLocation -> "Select a location first."
            KoardErrorType.NotReady.NotAuthenticated,
            KoardErrorType.KoardServiceErrorType.Unauthorized -> "Sign in first."
            KoardErrorType.NotReady.KernelAppNotInstalled ->
                "Install the Visa Tap to Pay Ready app."
            KoardErrorType.DeviceIntegrityError.DeveloperModeEnabled,
            KoardErrorType.NotReady.DeveloperModeEnabled -> "Disable developer options."
            else -> "Enrollment could not complete. Check setup or contact support."
        }
        // Record the type and a redacted shortMessage in your diagnostic handler.
        withContext(Dispatchers.Main) { showMessage(message) }
    }
}

For Result-returning APIs, put getOrThrow() inside the worker block and the surrounding try, then inspect the returned transaction's operation-specific status. For payments, use the canonical Running Payments implementation rather than adapting this enrollment helper into a payment retry loop. Unexpected exceptions should reach your app's fallback handler.

Troubleshooting and Support

Use Troubleshooting for NFC settings, enrollment, device integrity, and reader service contention. Include the SDK and Android versions, device model, operation, environment, full error type, redacted shortMessage, and transaction/event ID when available. For a reader event, also include statusCode, statusCodeDescription, actionStatus, and finalStatus when present. Omit API keys, credentials, and card data.

Published Sources

• Maven Central 1.0.7 AAR: KoardException, KoardError, Koard-facing error types, and the released numeric-code mapping.
• Public release artifact and changelog: readiness errors, reader service contention, API failures, and the published 1.0.7 behavior.