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, typically a 4xx error. They provide details about the cause of the request or processing failure, helping you quickly identify the issue.

Code: Numeric code that identifies the type of error.
Message: Text description of the error.

Example

The following example shows the response body for a request to Zero Auth when the service is not enabled:

[
  {
    "Code": 322,
    "Message": "Zero Dollar Auth is not enabled"
  }
]

⚠️
Important: Code and Message use the same values as ReturnCode and ReturnMessage, but they are returned in different situations. ReturnCode and ReturnMessage indicate the business outcome in HTTP 2xx responses.

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

Correct the submitted data: verify required fields, formats, and field size limits.
Verify credentials: check that MerchantId and MerchantKey are correct.
Confirm enabled services: verify that the required services are enabled in the E-commerce section of the Cielo portal.
Confirm authorized IP addresses: verify that the IP addresses used by your application are authorized in the Cielo portal.
Check API Status for persistent 5xx errors.

`Code` and `Message` Table

Code and Message use the same values as ReturnCode and ReturnMessage, but they are returned in different situations:

ReturnCode and ReturnMessage values are returned in successful HTTP operations (200 or 201);
Code and Message values are returned in HTTP error operations (for example, 400).

See the complete table below:

`ReturnCode` or `Code`	`ReturnMessage` or `Message`	Description
00	Internal error	Submitted data exceeds the field length
100	RequestId is required	The submitted field is empty or invalid.
101	MerchantId is required	The submitted field is empty or invalid.
102	Payment Type is required	The submitted field is empty or invalid.
103	Payment Type can only contain letters	Special characters are not allowed.
104	Customer Identity is required	The submitted field is empty or invalid.
105	Customer Name is required	The submitted field is empty or invalid.
106	Transaction ID is required	The submitted field is empty or invalid.
107	OrderId is invalid or does not exists	The submitted field exceeds the allowed length or contains special characters.
108	Amount must be greater or equal to zero	The transaction amount must be greater than "0".
109	Payment Currency is required	The submitted field is empty or invalid.
110	Invalid Payment Currency	The submitted field is empty or invalid.
111	Payment Country is required	The submitted field is empty or invalid.
112	Invalid Payment Country	The submitted field is empty or invalid.
113	Invalid Payment Code	The submitted field is empty or invalid.
114	The provided MerchantId is not in correct format	The provided MerchantId is not a GUID.
115	The provided MerchantId was not found	The MerchantID does not exist or belongs to a different environment (for example, Sandbox).
116	The provided MerchantId is blocked	Merchant is blocked. Check your merchant status on the Cielo website.
117	Credit Card Holder is required	The submitted field is empty or invalid.
118	Credit Card Number is required	The submitted field is empty or invalid.
119	At least one Payment is required	"Payment" node was not provided.
120	Request IP not allowed. Check your IP White List	IP address blocked for security reasons.
121	Customer is required	"Customer" node was not provided.
122	MerchantOrderId is required	The submitted field is empty or invalid.
123	Installments must be greater or equal to one	The number of installments must be greater than 1.
124	Credit Card is Required	The submitted field is empty or invalid.
125	Credit Card Expiration Date is required	The submitted field is empty or invalid.
126	Credit Card Expiration Date is invalid	The submitted field is empty or invalid.
127	You must provide CreditCard Number	Credit card number is required.
128	Card Number length exceeded	Credit card number exceeds 16 digits.
129	Affiliation not found	Payment method is not linked to the merchant, or the provider is invalid.
130	Could not get Credit Card	It may indicate that no card could be found for the provided card token, or that the query was interrupted.
131	MerchantKey is required	The submitted field is empty or invalid.
132	MerchantKey is invalid	The provided MerchantKey is not valid.
133	Provider is not supported for this Payment Type	The provided provider does not exist.
134	FingerPrint length exceeded	The provided data exceeds the field size limit.
135	MerchantDefinedFieldValue length exceeded	The provided data exceeds the field size limit.
136	ItemDataName length exceeded	The provided data exceeds the field size limit.
137	ItemDataSKU length exceeded	The provided data exceeds the field size limit.
138	PassengerDataName length exceeded	The provided data exceeds the field size limit.
139	PassengerDataStatus length exceeded	The provided data exceeds the field size limit.
140	PassengerDataEmail length exceeded	The provided data exceeds the field size limit.
141	PassengerDataPhone length exceeded	The provided data exceeds the field size limit.
142	TravelDataRoute length exceeded	The provided data exceeds the field size limit.
143	TravelDataJourneyType length exceeded	The provided data exceeds the field size limit.
144	TravelLegDataDestination length exceeded	The provided data exceeds the field size limit.
145	TravelLegDataOrigin length exceeded	The provided data exceeds the field size limit.
146	SecurityCode length exceeded	The provided data exceeds the field size limit.
147	Address Street length exceeded	The provided data exceeds the field size limit.
148	Address Number length exceeded	The provided data exceeds the field size limit.
149	Address Complement length exceeded	The provided data exceeds the field size limit.
150	Address ZipCode length exceeded	The provided data exceeds the field size limit.
151	Address City length exceeded	The provided data exceeds the field size limit.
152	Address State length exceeded	The provided data exceeds the field size limit.
153	Address Country length exceeded	The provided data exceeds the field size limit.
154	Address District length exceeded	The provided data exceeds the field size limit.
155	Customer Name length exceeded	The provided data exceeds the field size limit.
156	Customer Identity length exceeded	The provided data exceeds the field size limit.
157	Customer IdentityType length exceeded	The provided data exceeds the field size limit.
158	Customer Email length exceeded	The provided data exceeds the field size limit.
159	ExtraData Name length exceeded	The provided data exceeds the field size limit.
160	ExtraData Value length exceeded	The provided data exceeds the field size limit.
161	Boleto Instructions length exceeded	The provided data exceeds the field size limit.
162	Boleto Demostrative length exceeded	The provided data exceeds the field size limit.
163	Return Url is required	The return URL is not valid. Pagination or file extensions (for example, .PHP) are not allowed in the return URL.
166	AuthorizeNow is required	Required field not sent.
167	Antifraud not configured	Antifraude is not linked to the merchant registration.
168	Recurrent Payment not found	Recurrence not found.
169	Recurrent Payment is not active	Recurrence is not active. Execution has been halted.
170	Cartão Protegido not configured	The token is not linked to the merchant registration.
171	Affiliation data not sent	Order processing failed due to an affiliation error. Verify your credentials.
172	Credential Code is required	Credential validation failed.
173	Payment method is not enabled	The payment method is not linked to the merchant registration.
174	Card Number is required	The provided field is empty or invalid.
175	EAN is required	The provided field is empty or invalid.
176	Payment Currency is not supported	The provided field is empty or invalid.
177	Card Number is invalid	The provided field is empty or invalid.
178	EAN is invalid	The provided field is empty or invalid.
179	The max number of installments allowed for recurring payment is 1	The provided field is empty or invalid.
180	The provided Card PaymentToken was not found	Token not found.
181	The MerchantIdJustClick is not configured	Token is blocked.
182	Brand is required	Card brand was not provided.
183	Invalid customer bithdate	Invalid or future date of birth.
184	Request could not be empty	Request format error. Verify the submitted code.
185	Brand is not supported by selected provider	Card brand not supported by the API E-commerce Cielo.
186	The selected provider does not support the options provided (Capture, Authenticate, Recurrent or Installments)	The payment method does not support the requested operation.
187	ExtraData Collection contains one or more duplicated names
188	Avs with CPF invalid
189	Avs with length of street exceeded
190	Avs with length of number exceeded
191	Avs with length of district exceeded
192	Avs with zip code invalid
193	Split Amount must be greater than zero	The amount for a Split de Pagamento must be greater than 0.
194	Split Establishment is Required	The provided field is empty or invalid.
195	The PlataformId is required	The provided field is empty or invalid.
196	DeliveryAddress is required	The provided field is empty or invalid.
197	Street is required	The provided field is empty or invalid.
198	Number is required	The provided field is empty or invalid.
199	ZipCode is required	The provided field is empty or invalid.
200	City is required	The provided field is empty or invalid.
201	State is required	The provided field is empty or invalid.
202	District is required	The provided field is empty or invalid.
203	Cart item Name is required	The provided field is empty or invalid.
204	Cart item Quantity is required	The provided field is empty or invalid.
205	Cart item type is required	The provided field is empty or invalid.
206	Cart item name length exceeded	The provided data exceeds the field size limit.
207	Cart item description length exceeded	The provided data exceeds the field size limit.
208	Cart item sku length exceeded	The provided data exceeds the field size limit.
209	Shipping addressee sku length exceeded	The provided data exceeds the field size limit.
210	Shipping data cannot be null	Required field was not provided.
211	WalletKey is invalid	Invalid Visa Checkout data.
212	Merchant Wallet Configuration not found	The wallet is not enabled. See how to enable wallets on the Cielo website.
213	Credit Card Number is invalid	The provided credit card is invalid.
214	Credit Card Holder Must Have Only Letters	Must not contain special characters.
215	Agency is required in Boleto Credential	Required field was not provided.
216	Customer IP address is invalid	IP is blocked for security reasons.
220	Service tax can not be sent with 1 installment	`ServiceTaxAmount` requires installments greater than 1.
228	Customer Anddress Country is required	The provided field is empty or invalid.
233	Service tax not supported for the given brand.	`ServiceTaxAmount` is not supported by the card brand.
298	Split payment facilitator data not found	The provided `MerchantId` does not exist in the database of the selected environment (production or sandbox).
300	MerchantId was not found
301	Request IP is not allowed	The IP restriction service may be enabled, and the provided IP address is not configured. You can verify the IP addresses used by your merchant account on the Cielo website under E-commerce > Gestão API E-commerce > Gerenciamento de IPs. For more information, see the IP configuration documentation.
302	Sent MerchantOrderId is duplicated
303	Sent OrderId does not exist
304	Customer Identity is required	The provided field is empty or invalid.
306	Merchant is blocked	The merchant is blocked.
307	Transaction not found	Transaction not found or does not exist in the selected environment.
308	Transaction not available to capture	The transaction cannot be captured. We recommend querying the transactional status through the API. Capture can only be performed when the transaction status is 1. Each transaction can be captured only once, including in cases of partial capture. For more information, contact Cielo Support.
309	Transaction not available to void	The transaction cannot be voided. Please contact Cielo Support.
310	Payment method doest not support this operation	The requested operation is not supported by the selected payment method.
311	Refund is not enabled for this merchant	Voids after 24 hours are not authorized for the merchant.
312	Transaction not available to refund	The transaction does not allow voids after 24 hours.
313	Recurrent Payment not found	Recurrence is not enabled. Contact Cielo Support to have it enabled.
314	Invalid Integration
315	Cannot change NextRecurrency with pending payment	It is not allowed to change the recurrence date with a pending payment.
316	Cannot set NextRecurrency to past date	It is not allowed to change the recurrence date to a past date.
317	Invalid Recurrency Day
318	No transaction found
319	Smart recurrency is not enabled	The recurrence is not linked to the merchant registration.
320	Can not Update Affiliation Because this Recurrency not Affiliation saved
321	Can not set EndDate to before next recurrency
322	Zero Dollar Auth is not enabled	Zero Auth is not enabled. Contact Cielo Support to have it enabled.
323	Bin Query is not enabled	Consulta BIN is not enabled. Contact Cielo Support to have it enabled.
841	Status nao permite capturar	Attempt limit reached. Create a new transaction to perform the capture.

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