AI resources

Possible errors

See the list of possible errors returned by the APIs used in the Wallet Connect integration and how to correct them.

Agreements API

Errors returned in the agreement creation, payment token generation, query and cancellation operations.

Error Type	Status	Code	Description and possible solutions
Request error	400	`RedirectUriMismatch`	The redirect URI does not match the one registered for this application. Check the value sent in `return_uri` and confirm that it is registered in your application settings.
Request error	400	`ReturnUriNull`	The `return_uri` field is required and was not provided. Make the request again including it.
Request error	400	`ReturnUriTooLong`	The `return_uri` value exceeds the maximum allowed length of 2048 characters. Reduce the size of the URI sent.
Request error	400	`ExternalUserNull`	The `external_user` field is required and was not provided. Make the request again including the buyer's identifier in your system.
Request error	400	`ExternalFlowIdTooLong`	The `external_flow_id` value exceeds the maximum allowed length of 64 characters. Reduce the size of the identifier sent.
Request error	400	`AgreementDataDescriptionInvalid`	The `agreement_data.description` value is invalid. Check the content sent and respect the 256-character limit.
Request error	400	`CodeMismatch`	The provided code does not match the validation code for this agreement. Use the `code` returned in the `return_uri` or in the confirmation webhook of the corresponding agreement.
Request error	400	`InvalidCodeFormat`	The code format is invalid. It must be a 32-character lowercase alphanumeric string.
Request error	400	`AlreadyCreated`	A payment token for this agreement has already been generated. Use the `payer_token` obtained previously, as the same `code` cannot be reused.
Request error	400	`WindowExpired`	The time window for generating a payment token has expired. It will be necessary to create a new agreement and obtain a new approval from the buyer.
Request error	400	`AgreementNotConfirmedByUser`	The agreement has not been confirmed by the buyer yet. Wait for the approval flow to be completed before requesting the payment token.
Request error	400	`UserIdEqualsCollectorId`	The buyer and seller cannot be the same Mercado Pago user. Use distinct accounts to perform the agreement.
Request error	400	`invalid_path_param`	The `agreement_id` provided in the path is not valid. Please confirm it and provide a valid id to try again.
Request error	403	`forbidden`	You don't have permission to access the requested resource. Check whether the Access Token used has the permissions and scopes required for this operation.
Request error	404	`AgreementNotFound`	No agreement was found with the provided ID. This same response is returned when the agreement belongs to another application, in order to avoid exposing the existence of other customers' agreements.
Request error	404	`ClientNotOwner`	The agreement exists but was not created by the current application. The same `AgreementNotFound` response will be returned to avoid exposing the existence of other customers' agreements.
Request error	404	`AlreadyCancelled`	The agreement has already been cancelled. Remember that it can also be cancelled by the buyer through the Mercado Pago app or automatically when a new agreement is confirmed for the same buyer.
API error	500	`internal_error`	An internal server error occurred. Please try again later. If the problem persists, contact support, provide the `x-request-id` and more details about the operation performed.

Orders API

Errors returned in the order creation, capture, query, cancellation and refund operations.

Error Type	Status	Code	Description and possible solutions
Request error	400	`json_syntax_error`	An invalid JSON was sent. Make sure the request has a valid JSON structure and check the message returned in the error details to identify the problem.
Request error	400	`required_properties`	Some required properties are missing. Check the message returned in the error details and make sure to include all required properties according to the API documentation.
Request error	400	`unsupported_properties`	A property not supported by the API was sent. Review the request and remove or correct the unsupported properties.
Request error	400	`minimum_properties`	The minimum number of required properties was not sent. Add the necessary properties to complete the request.
Request error	400	`property_type`	The type of some informed property is invalid. Make sure the value sent in the request matches the expected type.
Request error	400	`property_value`	The value of some informed property is invalid. Check the value sent and adjust it to match the allowed values.
Request error	400	`maximum_items`	The array size exceeds the maximum allowed. Reduce the number of sent items. Remember that Wallet Connect orders accept only one payment transaction.
Request error	400	`minimum_items`	The array size is below the minimum allowed. Add more items to the request to meet the API requirements.
Request error	400	`invalid_properties`	Incorrect information was provided. Review the sent properties and check whether they comply with the API specifications.
Request error	400	`invalid_path_param`	The `order_id` provided in the path is not valid. Please confirm it and provide a valid id to try again.
Request error	400	`invalid_order_type`	The order `type` is invalid or unsupported. For payments with Wallet Connect, the only possible value is `online`.
Request error	400	`invalid_total_amount`	The value informed in `total_amount` does not match the sum of the `transactions.payments.amount` field of all transactions. Check whether the values are correct.
Request error	400	`empty_required_header`	The `X-Idempotency-Key` header is required and was not sent. Make the request again including it.
Request error	400	`invalid_idempotency_key_length`	The value sent in the `X-Idempotency-Key` header must be between 1 and 64 characters.
Request error	400	`refund_amount_exceeds`	The refund amount is greater than the amount available in the transaction. Check the available amount and adjust the requested value so as not to exceed this limit.
Authentication error	401	`unauthorized`	The value sent as the Access Token is incorrect. Check it and try sending the request again with the correct value.
Authentication error	401	`unauthorized_payer_token`	The `payer_token` provided is not authorized for this transaction. Check whether the token is valid, belongs to the authenticated buyer and whether the agreement has not been cancelled. If it has, the agreement flow must be repeated.
Authentication error	401	`invalid_credentials`	Test credentialsUnique access keys that we use to identify an integration in your account, linked to your application. For more information, access the link below.Credentials are not supported. Use test users with production credentials for the test environment (sandbox) and your production credentials for the production environment.
Processing error	402	`failed`	The order was created but some transaction failed. Check the `errors` field of the response to identify the reason, such as insufficient balance in the buyer's wallet (`insufficient_amount`).
Request error	404	`order_not_found`	Order not found. Check whether the sent id is correct.
Request error	404	`payment_not_found`	Payment not found. Check whether the sent `payment_id` is correct.
Request error	404	`transaction_not_found`	Transaction not found. Check whether the sent `transaction_id` is correct.
Idempotency error	409	`idempotency_key_already_used`	The value sent as the idempotency header (`X-Idempotency-Key`) has already been used. Each key must be unique to ensure the operation is performed only once. Use a new value for the next request.
Request error	409	`operation_not_supported`	The operation is not supported for this order. Check the order `status` and `status_detail` and try again.
Request error	409	`cannot_capture_order`	The order cannot be captured because it is not in a status that allows capture. Only orders with the `action_required` status created with `capture_mode` set to `manual` can be captured.
Request error	409	`cannot_cancel_order`	The order cannot be cancelled because it is not in a status that allows cancellation. Only orders with the `action_required` status can be cancelled. To reverse a payment that has already been captured, use the refund.
Request error	409	`order_already_canceled`	The order has already been cancelled. It is not possible to perform operations on an order that is already in this status.
Request error	409	`cannot_refund_order`	The order cannot be refunded. Make sure it is in a status that allows a refund to be performed.
Request error	409	`order_already_refunded`	The order has already been fully refunded. It is not possible to process a new refund in this scenario.
Request error	409	`order_refund_already_in_process`	There is already a full refund request in process for this order. Wait for it to complete before sending a new request.
Request error	422	`unprocessable_entity`	The payment profile associated with the `payer_token` is corrupted or incomplete. Ask the buyer to redo the wallet agreement.
Idempotency error	423	`resource_locked`	The idempotency key (`X-Idempotency-Key`) is locked by an ongoing request. Wait a few moments and try executing the request again.
Idempotency error	500	`idempotency_validation_failed`	Idempotency validation failed. Try resending the request with a new and unique idempotency key to avoid conflicts. If the problem persists, contact support, provide the `x-request-id` and more details about the operation performed.
API error	500	`internal_error`	An internal server error occurred. Please try again later. If the problem persists, contact support, provide the `x-request-id` and more details about the operation performed.

For more information about how to send the requests, requirements and necessary validations, please refer to our API ReferenceAPI.

PreviousWallet Connect API endpointsQuickly access the endpoints required to integrate Wallet Connect.

NextCredentialsCredentials are unique passwords used to identify an integration in your account. Learn how to obtain them.