SDK Error Codes

Use this reference to handle errors from KoardSDK 1.0.21, the published iOS release. The cases below are exported by its KoardSDK.xcframework and available with import KoardSDK. For recovery steps, see Troubleshooting.

Reading an SDK Error

The iOS wrapper is KoardMerchantSDKError. It conforms to KoardDescribableError and provides an errorDescription string. Switch on the enum case to decide how your app recovers. There is no public numeric code or errorCode property on this enum, and bridging it to NSError does not produce a documented Koard code.

A thrown error and a transaction outcome are different. A returned response can contain a declined, canceled, timed-out, or errored transaction without throwing. Follow Running Payments to inspect the transaction, partial approvals, and surcharge decisions before displaying a completed receipt.

KoardMerchantSDKError Reference

Associated values preserve additional context: .network(description:underlying:) carries a String and optional Error; .unknown(underlying:) carries an optional Error; .rateLimited(message:), .server(message:), and .readerTokenInvalid(...) carry optional strings. .unsupportedPlatform(requiredVersion:) and .invalidParameters(...) carry strings, and .failedToConfirmSurcharge(...) carries an Error. The two Tap to Pay wrappers carry the nested enums listed below.

HTTP Status Mapping

The published error-handling contract maps HTTP failures into Koard cases. These HTTP statuses are not a separate numeric Koard error enum.

Do not expect an HTTP 400 to become .invalidRequest, or a 404 to have its own enum case. The wrapper does not expose the original HTTP status as a dedicated property. A .server message may include it, but message parsing is not a supported classification mechanism.

Tap to Pay Configuration Errors

These are nested under .TTPConfigurationFailed(...) as KoardMerchantSDKError.TTPConfigurationError.

prepare() does not automatically link the account. linkAccountAsync() throws when linking fails or is declined. Follow Account linking and reader preparation instead of repeatedly presenting Apple's linking sheet.

Tap to Pay Payment Errors

These are nested under .TTPPaymentFailed(...) as KoardMerchantSDKError.TTPPaymentError.

Apple reader errors remain associated Error values where supplied. Their numeric codes and availability depend on Apple's error domain and OS version. They are not additional numeric Koard error codes.

Other Exported Error Data

The framework also exports RefundError, a KoardDescribableError with statusCode: Int, message: String, and errorDescription. If your caller receives this type, those are its diagnostic fields. It does not give every KoardMerchantSDKError a statusCode property, and the current refund API returns TransactionResponse on its success path.

ApiErrorDetail (detail, httpStatusCode) and ApiErrorItem (code, message, context) are exported Codable data models, not cases of the thrown error enum. Do not assume a caught KoardMerchantSDKError exposes those fields.

Handling Errors in Code

This reader-preparation example runs UI updates on the main actor and leaves account linking as an explicit merchant action. showMessage and offerAccountLinking are callbacks supplied by your app. For transaction handling, keep the complete Running Payments implementation as the source of truth.

import Foundation
import KoardSDK

@MainActor
func prepareReader(
    showMessage: (String) -> Void,
    offerAccountLinking: () -> Void
) async throws {
    do {
        try await KoardMerchantSDK.shared.prepare()
    } catch let cancellation as CancellationError {
        throw cancellation
    } catch let error as KoardMerchantSDKError {
        switch error {
        case .accountNotLinked:
            offerAccountLinking()
        case .unauthorized, .TTPConfigurationFailed(.notAuthenticated):
            showMessage("Sign in before preparing the reader.")
        case .readerTokenInvalid:
            showMessage("Check the SDK environment, then prepare the reader again.")
        case .rateLimited:
            showMessage("Too many requests. Wait before trying again.")
        case .network(_, let underlying):
            if (underlying as? URLError)?.code == .cancelled {
                throw CancellationError()
            }
            showMessage("Check your connection before preparing the reader again.")
        default:
            showMessage(error.errorDescription)
        }
    } catch {
        // Preserve an unexpected error for the caller's fallback handler.
        throw error
    }
}

For a payment catch block, handle .TTPPaymentFailed(.canceled) as cancellation. Keep a fallback branch for other errors and future cases, and never use a successful prepare() as proof that a payment succeeded.

Troubleshooting and Support

See Troubleshooting for setup, linking, token, and payment recovery. Include the SDK version, iOS version, operation, environment, enum case (including its nested case), redacted description, and transaction/event ID when available. Include an underlying error's domain/code only when that associated error exists. Omit credentials and card data.

Published Sources

• KoardSDK 1.0.21 public Swift interface: exported enum cases, associated values, and error data models.
• Published README and changelog: HTTP mapping, explicit linking, cancellation, and reader-token behavior.