Erros técnicos da API (Code e Message)

Erros retornados em `Code` e `Message`

Os parâmetros Code e Message aparecem no corpo da resposta quando ocorre um erro HTTP, geralmente o 4xx. Eles detalham a causa da falha na requisição ou no processamento, permitindo identificar rapidamente o problema.

Code: código numérico que identifica o tipo de erro;
Message: mensagem textual do erro.

Exemplo

Veja a seguir um exemplo de corpo da resposta para uma requisição ao VerifyCard quando existe erro no MerchantId

[
  {
    "Code": 114,
    "Message": "The provided MerchantId is not in correct format"
  }
]

⚠️
Importante: Code e Message seguem os mesmos valores que ProviderReturnCode e ProviderReturnMessage, mas são retornados em situações diferentes. ProviderReturnCode e ProviderReturnMessage indicam o resultado de negócio (junto ao provedor/adquirente) em respostas HTTP 2xx.
Os códigos e mensagens específicos valem para a adquirente Cielo; para outras adquirentes, consulte a documentação correspondente.

Como tratar os erros de `Code` e `Message`?

Corrija os dados enviados: verifique os campos obrigatórios, formatos e tamanhos;
Verifique credenciais MerchantId e MerchantKey;
Confirme os serviços habilitados no site Cielo, na aba E-commerce;
Confirme IPs autorizados no site Cielo;
Consulte API Status para erros 5xx persistentes.

Tabela de `Code` e `Message`

Code e Message apresentam os mesmos valores de ProviderReturnCode e ProviderReturnMessage, mas retornam em situações diferentes:

Os valores ProviderReturnCode e ProviderReturnMessage são retornados em operações HTTP de sucesso (200 ou 201);
Os valores Code e Message são retornados em operações HTTP de erro (ex.: 400).

⚠️
A tabela abaixo lista os códigos e mensagens específicos da adquirente Cielo. Se o estabelecimento utiliza outra adquirente integrada ao Gateway, consulte a documentação dela para os códigos e mensagens equivalentes.

Confira a tabela completa:

Reason Code	Reason Message	Descrição
00	Successful	Operação concluída com sucesso.
01	AffiliationNotFound	Afiliação/credencial do meio de pagamento não encontrada para o estabelecimento.
02	IssuficientFunds	Saldo insuficiente para realizar a operação.
03	CouldNotGetCreditCard	Não foi possível obter os dados do cartão de crédito (ex.: token inválido ou indisponível).
04	ConnectionWithAcquirerFailed	Falha na conexão com o adquirente.
05	InvalidTransactionType	Tipo de transação inválido.
06	InvalidPaymentPlan	Plano de pagamento (parcelamento) inválido.
07	Denied	Operação negada.
08	Scheduled	Operação agendada (ex.: recorrência).
09	Waiting	Operação em espera/processamento.
10	Authenticated	Transação autenticada com sucesso.
11	NotAuthenticated	Transação não autenticada.
12	ProblemsWithCreditCard	Problemas identificados com o cartão de crédito informado.
13	CardCanceled	Cartão cancelado.
14	BlockedCreditCard	Cartão de crédito bloqueado.
15	CardExpired	Cartão expirado.
16	AbortedByFraud	Operação abortada por suspeita/bloqueio de fraude.
17	CouldNotAntifraud	Não foi possível executar a análise antifraude.
18	TryAgain	Falha temporária; recomenda-se tentar novamente.
19	InvalidAmount	Valor da transação inválido.
20	ProblemsWithIssuer	Problemas com o emissor do cartão.
21	InvalidCardNumber	Número do cartão inválido.
22	TimeOut	Tempo limite de resposta excedido.
23	CartaoProtegidoIsNotEnabled	Serviço Cartão Protegido não habilitado para o estabelecimento.
24	PaymentMethodIsNotEnabled	Meio de pagamento não habilitado para o estabelecimento.
25	CouldNotFindPaymentToken	Token de pagamento não encontrado.
26	MerchantIdJustClickNotFound	MerchantId do Just Click não encontrado.
27	BrandNotSupported	Bandeira do cartão não suportada.
28	CardOptionsNotSupported	Opção de cartão (ex.: recorrência, parcelamento) não suportada pelo provedor.
29	WalletKeyIsInvalid	Chave da carteira digital (wallet) inválida.
30	MerchantWalletConfigurationNotFound	Configuração de carteira digital não encontrada para o estabelecimento.
31	BoletoRequiredDataNotSupported	Dados obrigatórios do boleto não suportados ou enviados incorretamente.
32	ConnectionWithAntifraudFailed	Falha na conexão com o serviço antifraude.
33	AbortedByCardVerification	Operação abortada pela verificação do cartão.
34	ProblemsWithAcquirer	Problemas com o adquirente.
35	ValidationError	Erro de validação dos dados enviados.
36	AcquirerTransactionNotFound	Transação não encontrada no adquirente.
37	SplitTransactionalError	Erro transacional no processamento do Split.
38	MerchantSplitConfigurationNotFound	Configuração de Split não encontrada para o estabelecimento.
39	SplitSoftDescriptorIsRequired	Soft descriptor do Split é obrigatório e não foi informado.
40	SplitFraudAnalysisIsRequired	Análise de fraude é obrigatória para a operação de Split.
41	SplitAntifraudMerchantConfigurationNotFound	Configuração antifraude do Split não encontrada para o estabelecimento.
42	ProviderNotFound	Provedor não encontrado.
43	PaymentSettingsNotFound	Configurações de pagamento não encontradas.
44	SubAcquirerMerchantConfigurationNotFound	Configuração do subadquirente não encontrada para o estabelecimento.
45	AbortedBySubAcquirer	Operação abortada pelo subadquirente.
98	InvalidRequest	Requisição inválida.
99	InternalError	Erro interno.
100	CieloPayCardHolderIsNotActive	Portador do cartão não está ativo no Cielo Pay.
101	CieloPayStrongValidationIsInvalid	Validação forte (autenticação) do Cielo Pay inválida.
102	CieloPayExpireDateDoesNotMatch	Data de validade informada não corresponde à registrada no Cielo Pay.
103	CieloPayCardHolderApiError	Erro na API do portador de cartão do Cielo Pay.
104	SplitPaymentFacilitatorDataNotFound	Dados do facilitador de pagamento do Split não encontrados.

Erros retornados em Code e Message

Como tratar os erros de Code e Message?

Tabela de Code e Message

Erros retornados em `Code` e `Message`

Como tratar os erros de `Code` e `Message`?

Tabela de `Code` e `Message`