AI resources

Possible mobile SDK errors

Check the list of possible errors returned by the Mercado Pago SDK for mobile integrations and how to fix them.

When the flow fails, the SDK delivers an error (MercadoPagoCheckoutResult.Error) with the fields errorCode (a stable value from the ErrorCode enum), errorMessage (error description), and errorLocalized (the step in the flow where it occurred).

kotlin
sealed class MercadoPagoCheckoutError(
    val errorCode: ErrorCode,
    val errorMessage: String,
    val errorLocalized: String,
    val errorCause: String? = null,
) : Throwable(message = errorMessage)

Code	Description	Cause	Possible solution
`NETWORK_CONNECTION_FAILED`	The mobile device could not open a network connection.	No internet, airplane mode, unreachable network, or DNS failure.	Check connectivity and offer a retry to the user.
`NETWORK_TIMEOUT`	The request exceeded the time limit.	Slow server or poor network quality.	Treat as recoverable and offer a retry to the user.
`SERVICE_ERROR`	Server error or failure communicating with the API.	Invalid API parameters, processing failure, or service business rule.	Check `errorMessage` and `errorLocalized` to identify the step. Confirm the data sent (`MPOrder`, `orderId`, amount, etc.) and the backend logs.
`INTEGRATION_ERROR`	The SDK is misconfigured or used incorrectly.	Missing required configuration, invalid initialization, or incorrect API usage (missing required parameters).	Ensure that `MercadoPagoSDK.initialize(...)` is called at app startup and before the checkout, with a valid Public KeyPublic key used in the frontend to initialize the integration and protect the data sent to Mercado Pago.Learn more about credentials (`publicKey`) and the corresponding country (`countryCode`).
`UNKNOWN`	Error that does not fit any other category.	Unexpected exception or undetermined error type.	Log `errorMessage` and `errorLocalized` for diagnosis and display a generic failure message with a retry option to the user.

PreviousPossible API errorsSee the main errors that may appear when submitting a payment through Checkout API using the Orders API.

Next3DS 2.0Learn how to integrate 3DS authentication technology with Checkout API.