Recursos para IA

Possíveis erros do SDK mobile

Veja a lista de possíveis erros retornados pelo Mercado Pago SDK para integrações mobile e como corrigi-los.

Quando o fluxo falha, o SDK entrega um erro (MercadoPagoCheckoutResult.Error) com os campos errorCode (um valor estável do enum ErrorCode), errorMessage (descrição do erro) e errorLocalized (etapa do fluxo onde ocorreu o erro).

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

Código	Descrição	Causa	Possível solução
`NETWORK_CONNECTION_FAILED`	O dispositivo mobile não conseguiu abrir conexão de rede.	Sem internet, modo avião, rede inacessível ou falha de DNS.	Verifique a conectividade e ofereça um retry ao usuário.
`NETWORK_TIMEOUT`	A requisição passou do tempo limite.	Servidor lento ou rede com qualidade ruim.	Trate como recuperável e ofereça um retry ao usuário.
`SERVICE_ERROR`	Erro no servidor ou na comunicação com a API.	Parâmetros da API inválidos, falha de processamento ou regra de negócio do serviço.	Verifique `errorMessage` e `errorLocalized` para a etapa. Confirme os dados enviados (`MPOrder`, `orderId`, valor, etc.) e os logs do backend.
`INTEGRATION_ERROR`	O SDK está mal configurado ou foi usado de forma incorreta.	Configuração obrigatória faltando, inicialização inválida ou uso incorreto da API (parâmetros obrigatórios ausentes).	Garanta que `MercadoPagoSDK.initialize(...)` seja chamado no início do aplicativo e antes do checkout, contendo uma Public KeyChave pública utilizada no frontend para inicializar a integração e proteger os dados enviados ao Mercado Pago.Mais informações sobre credenciais (`publicKey`) válida e o país (`countryCode`) correspondente.
`UNKNOWN`	Erro que não se encaixa nas demais categorias.	Exceção inesperada ou tipo de erro indeterminado.	Registre `errorMessage` e `errorLocalized` para diagnóstico e exiba uma mensagem genérica de falha com opção de retry ao usuário.

AnteriorPossíveis erros da APIVeja os principais erros que podem aparecer no envio do pagamento do Checkout API utilizando a Orders API.

Próximo3DS 2.0Saiba como integrar a tecnologia de autenticação 3DS com o Checkout API.