API technical errors (Code and Message)

Errors returned in `Code` and `Message`

The Code and Message parameters appear in the response body when an HTTP error occurs, usually a 4xx. They detail the cause of the failure in the request or processing, allowing you to quickly identify the problem.

Code: numeric code that identifies the error type;
Message: text message describing the error.

Example

See below an example of a response body for a VerifyCard request when there's an error in MerchantId

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

⚠️
Important: Code and Message follow the same values as ProviderReturnCode and ProviderReturnMessage, but are returned in different situations. ProviderReturnCode and ProviderReturnMessage indicate the business result (with the provider/acquirer) in HTTP 2xx responses.
The specific codes and messages apply to the Cielo acquirer; for other acquirers, check the corresponding documentation.

How to handle `Code` and `Message` errors?

Fix the submitted data: check required fields, formats, and sizes;
Check credentials: MerchantId and MerchantKey;
Confirm the enabled services on the Cielo website, under the E-commerce tab;
Confirm authorized IPs on the Cielo website;
Check API Status for persistent 5xx errors.

`Code` and `Message` table

Code and Message show the same values as ProviderReturnCode and ProviderReturnMessage, but are returned in different situations:

The ProviderReturnCode and ProviderReturnMessage values are returned in successful HTTP operations (200 or 201);
The Code and Message values are returned in HTTP error operations (e.g., 400).

⚠️
The table below lists the codes and messages specific to the Cielo acquirer. If the merchant uses another acquirer integrated with the Gateway, check that acquirer's documentation for the equivalent codes and messages.

See the full table:

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.

Errors returned in Code and Message

How to handle Code and Message errors?

Code and Message table

Errors returned in `Code` and `Message`

How to handle `Code` and `Message` errors?

`Code` and `Message` table