Recursos para IA
Principales estados y posibles errores
Consulta a continuación los principales estados de una transacción y los posibles errores de solicitud.
Después de la creación exitosa del payout, se generan las transacciones, que corresponden a las transacciones enviadas en el body de la solicitud. Cuando se crea una transacción, o cuando se consulta información relativa a ella, las respuestas retornarán los campos que permitirán conocer el estado en el que se encuentra.
status: este campo proporcionará información sobre el estado actual del procesamiento.status_detail: este campo pertenece a cada transacción e informa los motivos o detalles que resultaron en ese estado. Se devuelve comotransactions[].status_detailen una lista de transacciones y comostatus_detailen la respuesta de una transacción individual.
A continuación puedes ver todos los estados por los que puede pasar una transacción durante su procesamiento.
status | status_detail | Descripción |
approved | - | Se creó una transacción, pero aún no se ha procesado. Es un estado intermedio. |
approved | partially_refunded | La transacción fue parcialmente reembolsada por el banco de destino. |
canceled | - | Se canceló una transacción programada mediante el endpoint Cancelar una transacciónPUT. |
created | - | Se creó la transacción. |
error | failed | Cuando ocurre un error en el proceso de la transacción y no se logra acreditar el valor en la cuenta de destino. Consulta Mensajes de error de la transacción para más información sobre los mensajes retornados. |
error | invalid_chave_pix | La clave Pix enviada es inválida, pertenece a una cuenta diferente de la esperada, o está en la lista de bloqueo. |
error | missing_pix_alias | La clave Pix fue resuelta, pero la información de cuenta devuelta está incompleta para que la transferencia continúe. |
error | downstream_service_unavailable | Ocurrió una falla transitoria al resolver la clave Pix con el servicio de consulta de destinatario. Indica inestabilidad, no un rechazo de negocio. |
error | incomplete_recipient_data | La clave Pix se resolvió correctamente, pero los datos de la cuenta bancaria del destinatario están incompletos. |
error | account_finder_internal_error | Ocurrió un error interno inesperado al resolver la clave Pix. |
error | processing_cancelled | No se pudo completar la resolución de la clave Pix antes de que la solicitud fuera cancelada. |
processed | approved | El procesamiento de la transacción fue exitoso. |
refunded | refunded | La transacción fue totalmente reembolsada por el banco de destino. |
rejected | by_bank | La transacción fue rechazada por el banco de destino. Ejecuta nuevamente la solicitud. |
rejected | by_provider | La transacción fue rechazada por el proveedor. Ejecuta nuevamente la solicitud. |
rejected | high_risk | La transacción es rechazada debido al riesgo de fraude. Ejecuta nuevamente la solicitud. |
rejected | insufficient_funds | La transacción fue rechazada debido a fondos insuficientes en la cuenta de origen. Ejecuta nuevamente la solicitud. |
rejected | other_reason | La transacción fue rechazada por defecto debido a problemas internos durante el procesamiento. Ejecuta nuevamente la solicitud. |
rejected | review_manual | La transacción es rechazada y enviada para análisis de prevención de fraudes. Ejecuta nuevamente la solicitud. |
success | accredited | La transacción se encuentra acreditada en la cuenta de destino. |
success | in_progress | La acreditación de la transacción está en proceso, aún no está en la cuenta de destino. |
transaction_in_process | pending_authorized | La transacción está en curso, con estado final pendiente y esperando autorización. |
transaction_in_process | pending_bank | El banco de destino no respondió, por lo tanto, la transacción está pendiente de un estado final. |
Mensajes de error de la transacción
Cuando una transacción presenta status=error y status_detail=failed, la respuesta contiene un mensaje que explica la causa del error. Para las transacciones Pix, status_detail puede devolver los valores específicos que se muestran al final de la tabla.
status_detail | Mensaje |
failed | La cuenta del pagador no tiene fondos suficientes para completar esta transacción. Verifica el saldo y vuelve a intentarlo. |
failed | No fue posible procesar la transacción. Ocurrió un error al reservar los fondos. Por favor, intenta nuevamente más tarde o comunícate con soporte. |
failed | Cuenta TED no encontrada o inactiva. Verifica los datos de la cuenta y vuelve a intentarlo. |
failed | No se pudo procesar la transacción. Se produjo un error al procesar los datos de la transferencia. Por favor, intenta nuevamente más tarde o comunícate con soporte. |
failed | La transacción fue rechazada. Verifica los detalles y vuelve a intentarlo. Si el problema continúa, contacta a Soporte. |
failed | No se pudo procesar la transacción. Ocurrió un error interno. Por favor, intenta nuevamente más tarde o comunícate con Soporte. |
failed | Recurso no encontrado. Verifica los detalles de la transacción y vuelve a intentarlo. |
failed | Formato de fecha inválido. Verifica los campos de fecha en tu solicitud. |
failed | No fue posible obtener información bancaria. Verifica los datos de la cuenta bancaria y vuelve a intentarlo. |
failed | Información de usuario inválida. Verifica los IDs de usuario en tu solicitud. |
failed | Temporalmente no podemos mostrar el estado de esta transferencia. Esto no significa que la transferencia haya fallado. Por favor, actualiza la página en unos momentos o comunícate con Soporte. |
failed | Servicio temporalmente no disponible. Por favor, intenta nuevamente más tarde. |
failed | Ocurrió un error inesperado. Por favor, contacta a soporte para obtener ayuda. |
invalid_chave_pix | La clave Pix es inválida o pertenece a una cuenta diferente. Verifica la clave Pix y vuelve a intentarlo. |
missing_pix_alias | No fue posible obtener toda la información de la cuenta para esta clave Pix. Verifica la clave Pix y vuelve a intentarlo. |
account_finder_internal_error | Ocurrió un error inesperado al validar la clave Pix. Intenta nuevamente más tarde o comunícate con soporte. |
downstream_service_unavailable | No fue posible obtener la información de la cuenta para esta clave Pix. Intenta nuevamente más tarde. |
processing_cancelled | No fue posible completar la validación de esta clave Pix a tiempo. Vuelve a intentarlo. |
Aquí puedes encontrar los posibles errores que pueden ocurrir al realizar una solicitud de payout, junto con sus descripciones y posibles soluciones.
También pueden ocurrir los siguientes errores relacionados con los datos o el tipo de la cuenta de destino:
| Tipo de Error | Status | Código | Descripción y soluciones posibles |
| Error de solicitud | 400 | invalid_payout_id | El valor enviado en el parámetro de path payout_id es inválido o no identifica un payout existente. Verifica el identificador y vuelve a intentarlo. |
| Error de solicitud | 400 | invalid_transaction_id | El valor enviado en el parámetro de path transaction_id es inválido o no identifica una transacción existente. Verifica el identificador y vuelve a intentarlo. |
| Error de solicitud | 400 | invalid_signature | La firma enviada en el header X-signature es inválida o no coincide con el body cifrado de la solicitud. Verifica que la secret utilizada para generar la firma sea correcta y que el body enviado sea el mismo que se utilizó para generarla. Para más información, accede a Cifrado de seguridad. |
| Error de solicitud | 400 | idempotency_key_required | No se envió el header obligatorio X-Idempotency-Key. Inclúyelo con un valor único y vuelve a realizar la solicitud. |
| Error de solicitud | 400 | invalid_account | El objeto account se envió sin ningún campo de identificación. Envía al menos un email (cuenta de Mercado Pago) o un number/bank_id (cuenta bancaria). |
| Error de solicitud | 400 | invalid_account_type | El campo account_type se envió con un valor fuera del conjunto aceptado. Los valores aceptados son checking_account o savings. |
| Error de solicitud | 400 | invalid_account_type_for_site | El valor savings se envió en account_type fuera de Brasil. |
| Error de solicitud | 401 | invalid_token | El valor enviado como Access Token es incorrecto. Por favor, verifícalo y vuelve a realizar la solicitud enviando el valor correcto. |
| Error de solicitud | 403 | forbidden | Sin permiso para acceder al recurso. Verifica si el Access Token enviado tiene los permisos necesarios. |
| Error de solicitud | 404 | not_found | El recurso solicitado no fue encontrado o el valor enviado para identificarlo es inexistente. Valida la información enviada en los parámetros y vuelve a intentarlo. |
| Error de solicitud | 412 | precondition_failed | El estado en el que se encuentra la transacción no permite su cancelación. Solo pueden ser canceladas transacciones con status=pending o in_process. |
| Error de la API | 500 | internal_server_error | Ocurrió un error inesperado en el servidor. Vuelve a intentar la solicitud. Si el problema persiste, contacta al soporte. |
| Error de la API | 502 | bad_gateway | Ocurrió un error en la integración con un servicio externo. Vuelve a intentar la solicitud. Si el problema persiste, contacta al soporte. |