Introducción

Los errores son molestos - lo sabemos. Por eso tenemos artículos dedicados para cada error en nuestro DevPortal para ayudarte a resolverlos. Echa un vistazo al error a continuación, o simplemente busca el código de error que estás encontrando para ir directamente a las causas y soluciones.

Códigos de Respuesta

Usamos el siguiente código de estado HTTP en la respuesta dependiendo del éxito o fracaso:

Los errores de la API de Belvo se devuelven en formato JSON. Por ejemplo, un error podría verse así:

[
  {
    "request_id": "a6e1c493d7a29d91aed4338e6fcf077d",
    "message": "Este campo es requerido.",
    "code": "required",
    "field": "link"
  }
]

Típicamente, una respuesta de error tendrá los siguientes parámetros:

• request_id: un ID único para la solicitud, debes compartirlo con el equipo de soporte de Belvo para investigaciones.
• message: descripción del error en lenguaje humano.
• code: un código único para el error. Consulta la tabla a continuación para ver cómo manejar cada código de error.
• field (opcional): El campo específico en el cuerpo de la solicitud que tiene un problema.

Notas generales sobre el manejo de errores

Aquí está nuestra recomendación en términos de reintento en errores:

Errores 50x

Implemente un retroceso exponencial automatizado de hasta cinco reintentos. Recomendamos que utilice un intervalo base de tres segundos con un factor de dos. Por ejemplo, el primer reintento debe ser después de tres segundos, el segundo reintento es después de 6 segundos (2*3), el tercer reintento es después de 12 segundos (2*6), el cuarto reintento es después de 24 segundos (2*12), y el quinto reintento es después de 48 segundos (2*24).

Errores 40x

No deberías intentar nuevamente hacer solicitudes si recibes una respuesta 40x ya que esto es un error del cliente.

La única excepción es el error "Too Many Sessions", ya que significa que tu usuario está accediendo a la cuenta desde otro navegador al mismo tiempo. En este caso, por favor implementa la misma política de reintento que con los errores 50x.

400 activation_failed

[
  {
    "code": "activation_failed",
    "message": "The credentials provided were not accepted by the institution.",
    "request_id": "3e7b283c6efa449c9c028a16b5c249gg"
  }
]

Causa

Este error ocurre cuando Belvo no pudo activar automáticamente el acceso a la banca por internet para el usuario debido a información faltante (por ejemplo, el 🇲🇽 CVV o 🇲🇽 NIP estaban faltantes o se proporcionaron incorrectamente).

Solución

Pide al usuario que primero active su acceso a la banca por internet (ya sea contactando directamente al banco o intentando iniciar sesión en su cuenta de banca por internet) y luego pídele que conecte su cuenta nuevamente.

400 already_exists

[
    {
        "field": "details",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "pix_key": {
            "value": {
                "message": "This `pix_key__value` already exists. It is linked to BankAccount: d5c8cb5f-7845-4a23-a1fa-76c7ae7e5e36",
                "code": "already_exists"
            }
        }
    }
]

Causa

Estás intentando registrar una cuenta bancaria proporcionando un valor que ya está vinculado a una cuenta bancaria registrada en Belvo. Esto podría incluir:

• El identificador de la clave PIX de la cuenta bancaria
• El número de cuenta bancaria

{
  "institution": "f512d996-583a-4a91-8b5b-eba2e103b068",
  "holder": {
    "type": "BUSINESS",
    "information": {
        "identifier_type": "CNPJ",
        "name": "Caetano Veloso Entertainment Universe",
        "identifier": "231.002.990-00"
          }
     },
   "details": {
        "country": "BRA",
                "pix_key": "RANDOM://6c1c236c-a035-4b80-ab12-e38f88ce82ab", // Pix key already registerted in Belvo.
     }
}

{
  "institution": "f512d996-583a-4a91-8b5b-eba2e103b068",
  "holder": {
    "type": "BUSINESS",
    "information": {
        "identifier_type": "CNPJ",
        "name": "Caetano Veloso Entertainment Universe",
        "identifier": "231.002.990-00"
          }
     },
   "details": {
        "country": "BRA",
        "account_type": "CHECKINGS",
        "agency": "0444",
        "number": "45722-01" // Account number already registred in Belvo.
     }
}

Solución

Realiza una solicitud para obtener todas las cuentas bancarias para recibir una lista de todas las cuentas bancarias que has registrado, filtrando los resultados por los últimos cuatro dígitos de la cuenta bancaria para obtener los detalles.

400 blank

[
    {
        "field": "institution",
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "message": "Este campo no puede estar en blanco.",
        "code": "null"
    }
]

Causa

Enviaste una solicitud con una cadena vacía para un campo requerido. Por ejemplo:

{
    "institution": "", // Este campo es requerido y no puede ser una cadena vacía.
    "username": "bnk100",
    "password": "full",
}

Solución

• Revisa el mensaje de error para ver qué campo necesitas proporcionar. Si no estás seguro de qué información proporcionar o el formato, simplemente revisa nuestra documentación de referencia de la API.

400 cancellation_error

[
    {
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "message": "Payment Intent cannot be canceled because it is not SCHEDULED",
        "code": "cancellation_error"
    }
]

[
    {
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "message": "Payment Intent cannot be canceled as the cutoff time (23:59:00) has passed.",
        "code": "cancellation_error"
    }
]

Causa

Este error puede ocurrir cuando:

• Intentaste cancelar un payment intent que no estaba programado.
• Enviaste tu solicitud de cancelación después de la hora límite de las 23:59:00 (GMT-3) el día anterior a la fecha de liquidación programada.

400 does_not_exist

[
    {
        "field": "institution",
        "request_id": "744da6621cb09b3cbb8271d89fe09060",
        "message": "Object with name=narnia does not exist.",
        "code": "does_not_exist"
    }
]

Causa

Enviaste una solicitud donde proporcionaste un valor que no existe en la base de datos de Belvo. Por ejemplo:

{
    "institution": "narnia", // Esta institución no existe en la base de datos de Belvo.
    "username": "bnk100",
    "password": "full"
}

Solución

Revisa el mensaje de error para ver en qué campo proporcionaste un valor incorrecto. Luego:

• Asegúrate de que no hayas cometido errores tipográficos.
• Verifica si el valor que estás proporcionando debería estar presente en nuestra base de datos (por ejemplo, si haces una solicitud para un enlace que aún no fue registrado, recibirás un error).

400 duplicado

[
    {
        "request_id": "744da6621cb09b3cbb8271d89fe09060",
        "message": "Link already exists",
        "code": "duplicated",
        "institution_user_id": "4jlgn6vL7yifxMlhwFwTjbbzYxYoEEkJqK_CJhhZetI="
    }
]

Causa

Este error puede ocurrir cuando:

• Intentaste crear un link que ya ha sido asociado con tu cuenta.
• Tu usuario intentó crear un link con una cuenta que ya han conectado.

Solución

Puedes:

• Consultar tu base de datos para encontrar el institution_user_id y verificar si el link asociado id sigue siendo válido usando la solicitud Obtener los detalles de un link. Si el status no es valid, entonces solicita a tu usuario que actualice sus credenciales usando el Belvo widget en modo de actualización.
• Consultar tu base de datos para encontrar el institution_user_id y usar el link asociado id para eliminar el link de la base de datos de Belvo usando la solicitud Eliminar un link. Una vez que hayas eliminado el link, puedes pedir a tu usuario que conecte su cuenta nuevamente.

400 null

[
    {
        "field": "institution",
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "message": "This field may not be null.",
        "code": "null"
    }
]

Causa

Hiciste una solicitud sin proporcionar datos en un campo requerido. Por ejemplo:

{
    "institution": , // Este campo es requerido.
    "username": "bnk100",
    "password": "full",
}

Solución

Revisa el mensaje de error para ver qué campo necesitas proporcionar. Si no estás seguro de qué información proporcionar o el formato, simplemente revisa nuestra documentación de referencia de la API.

400 requerido

[
    {
        "field": "username",
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "message": "Este campo es requerido.",
        "code": "required"
    }
]

[
    {
        "field": "amount",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "message": "Este campo es requerido.",
        "code": "required"
    }
]

Causa
Enviaste una solicitud sin un campo requerido. Por ejemplo:

{
    "institution": "erebor_mx_retails",
            // Cuando estás registrando un nuevo enlace, debes proporcionar un username.
    "password": "full"
}

{
     "allowed_payment_method_types": [
          "pse"
     ],
     "payment_method_details": {
          "pse": {
               "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"
          }
     },
     "callback_urls": {
          "cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
          "success": "https://www.acmecorp.com/checkout/3487548/success"
     },
           // Cuando estás creando un enlace de pago, debes proporcionar un amount de pago.
     "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
     "description": "Awesome training Sneaker",
     "provider": "payments_way"
}

Solución

• Revisa el mensaje de error para ver qué campo necesitas proporcionar. Si no estás seguro de qué información proporcionar o el formato, simplemente revisa nuestra documentación de referencia de la API.

400 institution_down

[
  {
    "code": "institution_down",
    "message": "The financial institution is down, try again later",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

Causa

Este error ocurre cuando el sitio web de la institución a la que estás intentando acceder está caído debido a mantenimiento u otros problemas, lo que significa que Belvo no puede crear nuevos enlaces o recuperar nuevos datos.

Solución

Puedes intentar acceder a la institución más tarde. Asegúrate de suscribirte a nuestra Página de Estado de Instituciones para saber tan pronto como una institución no esté disponible.

Puedes eliminar una institución que actualmente no está disponible utilizando el parámetro institutions en la configuración de inicio y omitiendo la institución de la lista.

Mensaje de error del widget

400 institution_inactive

[
  {
    "code": "institution_inactive",
    "message": "The institution has been temporarily deactivated",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

Causa

Este error ocurre cuando nosotros (Belvo) hemos desactivado la institución en nuestra API.

Solución

Puedes intentar de nuevo más tarde, una vez que Belvo haya reactivado la institución.

400 institution_unavailable

[
  {
    "code": "institution_unavailable",
    "message": "The financial institution is unavailable",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

Causa

Este error ocurre cuando el sitio web de la institución a la que estás intentando acceder está inactivo debido a mantenimiento u otros problemas, lo que significa que Belvo no puede crear nuevos enlaces o recuperar nuevos datos.

Solución

Puedes intentar acceder a la institución más tarde. Asegúrate de suscribirte a nuestra Página de Estado de Instituciones para saber tan pronto como una institución no esté disponible.

Puedes eliminar una institución que actualmente no está disponible utilizando el parámetro institutions en la configuración de inicio y omitiendo la institución de la lista.

Mensaje de error del widget

400 inválido

[
    {
        "field": "date_to",
        "request_id": "a7ad9a4ad8b13f8f800f8f5b69c7856f",
        "message": "La fecha tiene un formato incorrecto. Usa uno de estos formatos en su lugar: YYYY-MM-DD.",
        "code": "invalid"
    }
]

[
    {
        "field": "link",
        "request_id": "448f2b58fc88b2c5a9db6c9175494950",
        "message": "“YTZjMDA3YjktZTk5Yy00MDczLTgzNGItOGM3NzA1MTMyZGU3" no es un UUID válido.",
        "code": "invalid"
    }
]

[
    {
        "field": "payments_way",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "terminal_id": [
            {
                "message": "El terminal_id es inválido, intenta de nuevo o contacta al soporte de Belvo.",
                "code": "invalid"
            }
        ]
    }
]

[
    {
        "field": "payments_way",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "form_id": [
            {
                "message": "El form_id es inválido, intenta de nuevo o contacta al soporte de Belvo.",
                "code": "invalid"
            }
        ]
    }
]

[
    {
        "field": "resources",
        "request_id": "a7ad9a4ad8b13f8f800f8f5b69c7856f",
        "message": "La institución solo soporta los siguientes recursos: {1}, {2}",
        "code": "invalid"
    }
]

Causa

Enviaste una solicitud donde proporcionaste un valor en un formato inválido. Esto podría incluir:

• El formato de las credenciales de inicio de sesión es incorrecto.
• El formato de la fecha es incorrecto.
• El UUID no es válido.
• El terminal_id no es válido.
• El form_id no es válido.
• Los recursos que has incluido en fetch_resources no son soportados por la institución.

Por ejemplo:

{
    "link": "a6c007b9-e99c-4073-834b-8c7705132de7",
    "date_from": "2020-01-01",
    "date_to": "2020-02" // Aquí, el formato de la fecha debe ser YYYY-MM-DD
}

{
    "link": "a6c007b9-e99c" // Aquí, el ID del link no es un UUID válido.
}

{
     "holder": {
          "type": "BUSINESS",
          "information": {
               "name": "Trusty documentation services"
          }
     },
     "providers": {
          "payments_way": {
               "terminal_id": "1200", // Belvo te proporciona el terminal_id correcto que necesitas para crear una cuenta bancaria.
               "form_id": "3211", // Belvo te proporciona el form_id correcto que necesitas para crear una cuenta bancaria.
          }
     },
}

Solución

Revisa el mensaje de error para ver qué campo es inválido y por qué. Luego, si necesitas más información, consulta nuestra documentación de API para saber cuál es el formato válido para el campo.

400 invalid_choice

[
    {
        "field": "access_mode",
        "request_id": "ce49b6af6710bb0c7a2a456c223dde21",
        "message": "\"Dominik\" is not a valid choice.",
        "code": "invalid_choice"
    }
]

Causa
Hiciste una solicitud en la que en uno de los campos proporcionaste un valor que no era válido (por ejemplo, puede que solo acepte ciertas cadenas, similar a un enum). Por ejemplo:

{
    "institution": "erebor_mx_retail",
    "username": "bnk100",
    "password": "full",
    "access_mode": "Australia" // Este no es un valor válido, ya que en la documentación se indica que es un enum: single o recurrent
}

Solución

• Revisa el mensaje de error para ver en qué campo proporcionaste un valor incorrecto. Luego consulta nuestra documentación para ver qué valor deberías proporcionar para este campo.

400 invalid_credentials_storage

[
    {
        "request_id": "ce49b6af6710bb0c7a2a456c223dde21",
        "message": "Recurrent links must store the credentials",
        "code": "invalid_credentials_storage"
    }
]

Causa
Hiciste una solicitud donde para un enlace recurrente configuraste el parámetro credentials_storage a nostore o a un rango de fechas entre 1d a 365d.

{
    "institution": "tatooine_mx_fiscal",
    "username": "PFIS010101000",
    "password": "individual",
    "access_mode": "recurrent",
    "credentials_storage": "nostore" // Para enlaces recurrentes, esto debe configurarse para almacenar
}

Solución

• Si deseas crear un enlace recurrente, cambia el valor de credentials_storage a store.
• Si deseas crear un enlace único y no almacenar credenciales, cambia el access_mode a single.

400 invalid_fetch_resources

[
    {
        "request_id": "ce49b6af6710bb0c7a2a456c223dde21",
        "message": "Single links without stored credentials must fetch resources",
        "code": "invalid_fetch_resources"
    }
]

Causa
Intentaste crear un enlace donde configuraste el parámetro credentials_storage a nostore y no pasaste ningún recurso en el parámetro fetch_resources. Para enlaces donde no almacenamos credenciales, debes pasar al menos un recurso en fetch_resources.

{
    "institution": "tatooine_mx_fiscal",
    "username": "PFIS010101000",
    "password": "individual",
    "access_mode": "recurrent",
    "credentials_storage": "nostore",
  	"fetch_resources": []
}

Solución

Enumera los recursos que deseas recuperar en el parámetro fetch_resources. Por ejemplo: "fetch_resources": ["ACCOUNTS", "OWNERS", "TRANSACTIONS"] .

400 invalid_link

[
  {
    "code": "invalid_link",
    "message": "The link has been invalidated. You may need to update link credentials",
    "request_id": "9b7b283c6efa449c9c028a16b5c249fd"
  }
]

Causa

Este error ocurre cuando intentas acceder a una cuenta pero las credenciales del usuario ya no son válidas, lo que provoca un error por parte de la institución.

Solución

Pide a tu usuario que proporcione sus credenciales actualizadas. Para facilitar las cosas, te recomendamos encarecidamente que uses nuestro Widget en Modo de Actualización.

400 invalid_period

[
    {
        "message": "The number of days between date_from and date_to must be at least 90 days",
        "code": "invalid_period",
        "request_id": "a66a4fdae4ab8cfc1ed9ee9246aa6890"
    }
]

Causa

Este error ocurre cuando solicitas ingresos para un enlace dentro de un rango de fechas dado, sin embargo, el período entre date_from y date_to es menor a 90 días.

Solución

Asegúrate de que el período entre date_from y date_to sea igual o mayor a 90 días.

400 login_error

[
  {
    "code": "login_error",
    "message": "Credenciales inválidas proporcionadas para iniciar sesión en la institución",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "La institución requiere un token MFA, pero aún no es compatible con Belvo.",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "Imposible iniciar sesión, ocurrió algo inesperado al iniciar sesión en la institución. Inténtalo de nuevo más tarde.",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "Inicio de sesión no intentado debido a credenciales inválidas",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "Faltan credenciales para iniciar sesión en la institución",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "El acceso a la cuenta del usuario fue prohibido por la institución",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "El acceso a la cuenta del usuario fue prohibido por la institución",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "La cuenta del usuario está bloqueada, el usuario necesita contactar a la institución para desbloquearla",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

Causa

Este error puede ocurrir cuando:

• las credenciales que tu usuario proporciona son incorrectas o faltan.
• el token MFA que tu usuario proporciona no es compatible con Belvo.
• hay un problema con la institución que impide los inicios de sesión.
• la cuenta del usuario está bloqueada o el usuario no tiene permiso para acceder a su banca por internet.

Solución

• Pide a tu usuario que proporcione sus credenciales correctas o el token MFA. Usa nuestro widget para hacerlo aún más fácil (nosotros hacemos todo el trabajo pesado por ti).
• Pide a tu usuario que confirme con su banco que su cuenta está activa y que no está bloqueada.
• Si hay un problema con la institución, intenta iniciar sesión en otro momento.

400 max_digits

[
    {
        "field": "amount",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "message": "Ensure that there are no more than 12 digits in total.",
        "code": "max_digits"
    }
]

Causa
Enviaste una solicitud con el formato de cantidad incorrecto. Por ejemplo:

{
     "allowed_payment_method_types": [
          "pse"
     ],
     "payment_method_details": {
          "pse": {
               "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"
          }
     },
     "callback_urls": {
          "cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
          "success": "https://www.acmecorp.com/checkout/3487548/success"
     },
     "amount": 10000000000000000000,
     "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
     "description": "Awesome training Sneaker",
     "provider": "payments_way"
}

Solución

Revisa el mensaje de error para ver por qué el formato de la cantidad es inválido. Si no estás seguro de qué información proporcionar o el formato, simplemente revisa nuestra documentación de referencia de la API para saber cuál es el formato válido para el campo.

400 max_decimal_places

[
    {
        "field": "amount",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "message": "Ensure that there are no more than 2 decimal places.",
        "code": "max_decimal_places"
    }
]

Causa
Enviaste una solicitud con el formato de cantidad incorrecto. Por ejemplo:

{
     "allowed_payment_method_types": [
          "pse"
     ],
     "payment_method_details": {
          "pse": {
               "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"
          }
     },
     "callback_urls": {
          "cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
          "success": "https://www.acmecorp.com/checkout/3487548/success"
     },
     "amount": 10.123,
     "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
     "description": "Awesome training Sneaker",
     "provider": "payments_way"
}

Solución

Revisa el mensaje de error para ver por qué el formato de la cantidad es inválido. Si no estás seguro de qué información proporcionar o el formato, simplemente revisa nuestra documentación de referencia de la API para saber cuál es el formato válido para el campo.

400 min_value

[
    {
        "field": "amount",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "message": "Ensure this value is greater than or equal to 0.01.",
        "code": "min_value"
    }
]

Causa
Enviaste una solicitud con el formato de cantidad incorrecto. Por ejemplo:

{
     "allowed_payment_method_types": [
          "pse"
     ],
     "payment_method_details": {
          "pse": {
               "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc"
          }
     },
     "callback_urls": {
          "cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
          "success": "https://www.acmecorp.com/checkout/3487548/success"
     },
     "amount": 0.12,
     "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
     "description": "Awesome training Sneaker",
     "provider": "payments_way"
}

Solución

Revisa el mensaje de error para ver por qué el formato de la cantidad es inválido. Si no estás seguro de qué información proporcionar o el formato, simplemente revisa nuestra documentación de referencia de la API para saber cuál es el formato válido para el campo.

400 not_a_list

[
    {
        "message": 'Expected a list but got type "str".',
        "code": "not_a_list",
        "request_id": "d5af76cc66e0231e2be7f7be5c41170a"
    }
]

Causa
Enviaste una solicitud donde en lugar de enviar un array de datos, enviaste solo una lista. Por ejemplo:

{
    "fetch_resources": "ACCOUNTS,OWNERS", // Aquí, fetch_resources tiene que ser un array de valores
}

{
    "fetch_resources": ["ACCOUNTS","OWNERS"],
}

Solución

Revisa tu solicitud JSON y consulta nuestra documentación para ver qué campo debería ser un array.

400 parse_error

[
    {
        "message": "JSON parse error - Expecting property name enclosed in double quotes: line 3 column 1 (char 54)",
        "code": "parse_error",
        "request_id": "d5af76cc66e0231e2be7f7be5c41170a"
    }
]

Causa
Enviaste una solicitud con JSON inválido. Por ejemplo:

{
    "link": "a6c007b9-e99c-4073-834b-8c7705132de7", // Aquí, no deberías tener una coma al final en tu solicitud
}

Solución

Verifica el payload JSON (quizás solo te falta una coma o una comilla) e inténtalo de nuevo.

400 session_expired

[
  {
    "code": "session_expired",
    "message": "The session you are trying to resume has expired, please start again from register/retrieve endpoint",
    "request_id": "6e7b283c6efa449c9c028a16b5c249fa"
  }
]

Causa

Este error ocurre cuando intentas reanudar una sesión de solicitud que ya ha expirado. Esto suele suceder porque el usuario tardó demasiado en proporcionar su token de autenticación.

Para las solicitudes que requieren un token, hay un período de tiempo en el que el usuario puede proporcionar su token. El período varía de una institución a otra. Puedes verificar cuánto tiempo tiene el usuario para ingresar su token utilizando el parámetro expiry en la respuesta 428 token_required.

Solución

Desafortunadamente, necesitarás comenzar todo el proceso de inicio de sesión con tu usuario nuevamente.

Mensaje de error del widget

400 session_expired_ob

[
  {
    "code": "session_expired_ob",
    "request_id": "6e7b283c6efa449c9c028a16b5c249fa"
  }
]

Causa

Puedes recibir este error por las siguientes razones:

1. El access_token que generaste no se utilizó dentro del período de expiración de 10 minutos.
2. En lugar de generar un nuevo access_token para el widget para el usuario dado, utilizaste un access_token generado para otro usuario que ya creó un enlace usando el widget.
3. Tu usuario no hizo clic en el botón Ir para a instituição (Ir a la institución) en el widget dentro de los 60 segundos de aparecer la pantalla.

Solución

Desafortunadamente, necesitarás iniciar el proceso del widget con tu usuario nuevamente. Por favor asegúrate de que:

1. Asegúrate de usar el access_token para generar el widget tan pronto como se cree. Si pasan 10 minutos o más, necesitarás crear un nuevo access_token.
2. Asegúrate de crear siempre un nuevo access_token para cada usuario.
3. Nuestro equipo de UX está mejorando el flujo para incitar al usuario a continuar el flujo dentro de los 60 segundos asignados.

Mensaje de error del widget

400 too_many_sessions

[
	{
		"code": "too_many_sessions",
		"message": "Impossible to login, a session is already opened with the institution for these credentials",
		"request_id": "3e7b283c6efa449c9c028a16b5c249fd"
	}
]

Causa

Este error ocurre cuando:

• un usuario está intentando iniciar sesión en su institución a través de Belvo mientras ya está conectado a su institución en un navegador web o aplicación móvil.
• haces una solicitud de información mientras Belvo está extrayendo datos de la institución para ese usuario.

Solución

Intenta:

• Informar a tu usuario que cierre sus sesiones web y de aplicación para la institución dada.
• Esperar 120 segundos y volver a intentar tu solicitud, asegurándote de que Belvo haya terminado el proceso de extracción de datos.

Mensaje de error del widget

400 unavailable_data

[
    {
        "message": "The institution did not return any data for the request.",
        "code": "unavailable_data",
        "request_id": "c76f4d0320b923eb3068f5e2c0fab18f"
    }
]

Causa

Este error ocurre cuando tu solicitud fue correctamente formada y enviada, sin embargo, la institución no devolvió ningún dato para tu solicitud.

Solución

Recomendamos primero verificar nuestra Página de Estado de Instituciones para ver si hay algún incidente con la institución que esté prohibiendo la extracción de datos. Si no hay incidentes activos para la institución, puedes reintentar la solicitud. Si sigues recibiendo este error, contacta a nuestro equipo de soporte, asegurándote de incluir el request_id que recibes en el mensaje.

400 unconfirmed_link

[
    {
        "message": "The link creation has not been completed yet",
        "code": "unconfirmed_link",
        "request_id": "c76f4d0320b923eb3068f5e2c0fab18f"
    }
]

Causa

Este error ocurre cuando intentas acceder a un link que fue pausado previamente (y como tal no está activo ahora).

Solución

Pide a tu usuario que proporcione un token MFA a través de nuestro widget en modo de actualización para completar un primer inicio de sesión. Después de que el usuario complete el proceso exitosamente, podrás recuperar los datos.

400 unsupported_operation

[
    {
        "message": "The resource you are trying to access is not supported by this institution",
        "code": "unsupported_operation",
        "request_id": "a66a4fdae4ab8cfc1ed9ee9246aa6890"
    }
]

[
    {
        "message": "For single links, you must set fetch_historical to true when using the resources request parameter.",
        "code": "unsupported_operation",
        "request_id": "a66a4fdae4ab8cfc1ed9ee9246aa6890"
    }
]

Causa

Este error ocurre cuando:

• Intentas acceder a alguna operación de datos que Belvo no soporta para una institución. Por ejemplo, intentar acceder al recurso de Transactions para instituciones fiscales.
• Realizas una solicitud que requiere que se complete alguna lógica de negocio. Por ejemplo, al usar el parámetro fetch_resources en la creación de un solo enlace, también debes establecer fetch_historical a true

Solución

Asegúrate de que:

• La operación del recurso (por ejemplo, solicitar Transactions) es soportada para esa institución.
• Tu solicitud cumple con toda la lógica de negocio requerida.

Mensaje de error del widget

400 validation_error

[
    {
        "message": "Bad request",
        "code": "validation_error",
        "request_id": "e912d014d7976c3172bb8e65c7a22194"
    }
]

Causa

Enviaste una solicitud donde:

• Las credenciales proporcionadas no coincidieron con los campos esperados, lo que llevó a un error de validación de campo por parte de la institución.

Por ejemplo:

{
    "link": "a6c007b9-e99c-4073-834b-8c7705132de7",
    "date_from": "2020-01-01",
    "date_to": "2021-03-30" // Entre date_from y date_to hay más de 365 días
}

Solución

Obtén los detalles de la institución usando nuestro endpoint de Instituciones y revisa el objeto form_fields para obtener información sobre qué campos deben proporcionarse y su formato.

401 authentication_failed

[
    {
        "message": "Invalid Secret Keys",
        "code": "authentication_failed",
        "request_id": "5c09677ecf78e1d4501547252a0c4e77"
    }
]

Causa

Este error ocurre cuando intentas hacer una llamada a la API usando credenciales incorrectas de la API de Belvo (ya sea tu secret key o secret password, o ambos, son incorrectos).

Solución

Verifica las credenciales que estás usando con las que están en tu dashboard. Quizás estás usando tus credenciales de sandbox para acceder a datos de producción (o viceversa). Nota: Si no estás seguro sobre tu secretPassword, revisa el correo de confirmación que recibiste de Belvo.

401 consent_without_accounts

[
    {
        "message": "Information cannot be retrieved as the consent has no associated accounts",
        "code": "consent_without_accounts",
        "request_id": "5c09677ecf78e1d4501547252a0c4e77"
    }
]

Causa

Este error ocurre cuando tu usuario ha eliminado cuentas asociadas con el consentimiento que proporcionaron. Por ejemplo, cuando tu usuario generó su consentimiento por primera vez, tenían una cuenta corriente y una cuenta de préstamo en la institución, pero han cerrado esas cuentas desde entonces.

Solución

Comunícate con tu usuario para confirmar si han eliminado su cuenta y pídeles que generen un nuevo consentimiento en su institución actual.

403 access_to_production_denied

[
    {
        "message": "You don’t have access to production API.",
        "code": "access_to_production_denied",
        "request_id": "d5af76cc66e0231e2be7f7be5c41170a"
    }
]

Causa

Este error ocurre cuando intentas acceder al entorno de producción de Belvo sin los permisos correctos.

Solución
Contacta a nuestro equipo de ventas para solicitar acceso al entorno de producción.

403 access_to_resource_denied

[
    {
        "message": "You don't have access to this resource.",
        "code": "access_to_resource_denied",
        "request_id": "d5af76cc66e0231e2be7f7be5c41170a"
    }
]

Causa

Este error ocurre cuando intentas acceder a un recurso de Belvo sin los permisos correctos.

Solución
Contacta a nuestro equipo de ventas para solicitar acceso a este recurso.

403 Prohibido

<html><head><title>403 Prohibido</title></head><body>

<center><h1>403 Prohibido</h1></center>

<hr><center>openresty/1.15.8.2</center>

</body></html>

Causa

Este error ocurre cuando realizas un gran volumen de solicitudes (más de 80 solicitudes en 30 segundos) en rápida sucesión desde la misma dirección IP.

Solución

Si esperas tener consistentemente grandes volúmenes de llamadas desde la misma dirección IP, por favor contacta a nuestro equipo de Éxito del Cliente.

403 permission_denied

Causa

Este error ocurre cuando nosotros (Belvo) tenemos prohibido acceder a un recurso determinado en la institución, o has excedido tu límite de solicitudes.

Solución
Si pudiste acceder a este recurso anteriormente, intenta nuevamente más tarde. Nosotros (Belvo) monitoreamos activamente estos errores y asignamos ingenieros para corregir la situación lo antes posible.

403 quota_limit_reached

[
    {
        "message": "The quota limit has been reached.",
        "code": "quota_limit_reached",
        "request_id": "1d1c4f427dac394a96c3fa49568f2a38"
    }
]

Causa

Este error ocurre cuando has excedido el límite de Link en el entorno de desarrollo.

Solución

Para seguir usando el entorno de desarrollo, necesitas eliminar suficientes Links para estar por debajo del límite del entorno.

404 not_found

[
    {
        "message": "Not found.",
        "code": "not_found",
        "request_id": "1d1c4f427dac394a96c3fa49568f2a38"
    }
]

[
    {
        "message": "The credentials of this link have expired",
        "code": "expired_credentials",
        "request_id": "4d3de3930431496799eafc5c91e5bcfe"
    }
]

Causa

Hiciste una solicitud donde:

• proporcionaste la URL incorrecta.
• usaste un ID (para un link, cuenta, transacción, etc.) que no está asociado con tu cuenta de Belvo.
• hiciste una solicitud para un link donde el credentials_storage estaba configurado como no_store o 30d, y Belvo ya no tiene estas credenciales almacenadas para recuperar información.

Solución

Asegúrate de que:

• Estás usando la URL correcta (verifica errores tipográficos y nuestra documentación de referencia de la API).
• Estás usando un ID que está asociado con tu cuenta de Belvo.

En el caso donde el link fue creado con el credentials_storage configurado como no_store o 30d, necesitarás pedirle al usuario que vuelva a conectar su cuenta.

405 method_not_allowed

[
    {
        "message": "Method \"PATCH\" not allowed.",
        "code": "method_not_allowed",
        "request_id": "8ea4cd36ad39db3823b89b31aea74581"
    }
]

Causa

Este error ocurre cuando intentas usar un método de API que no está permitido para el recurso dado (por ejemplo, una solicitud PATCH para endpoints Fiscales).

Solución

Verifica qué métodos están permitidos para el recurso dado en nuestra Documentación de Referencia de API.

408 request_timeout

[
  {
    "code": "request_timeout",
    "message": "The request timed out, you can retry asking for less data by changing your query parameters",
    "request_id": "5c7b283c6efa449c9c028a16b5c249fd"
  }
]

Causa

Belvo tiene un límite respecto al tiempo que toma iniciar sesión, recuperar datos de la cuenta y cerrar sesión, que está establecido en cinco (5) minutos. Ocurre un timeout cuando hay una gran cantidad de datos y no se pudo obtener todo dentro del tiempo asignado.

Por ejemplo, si una cuenta tiene más de 2000 transacciones por cuenta por mes, podrías recibir un error de request_timeout.

Solución

Cuando ocurre un timeout, nuestra API aún guarda la mayor cantidad de datos que pudo recuperar. Por lo tanto, puedes intentar hacer la misma solicitud nuevamente y recuperar todos los datos con éxito.

Si sigues recibiendo errores de timeout para varios links, o tres timeouts para el mismo link, repórtalo a Belvo y proporciona los request_ids.

Mensaje de error del widget

409 link_refreshed

[
  {
    "code": "link_refreshed",
    "message": "The link has already been refreshed. Please wait X minutes before trying again.",
    "request_id": "9e7b283c6efa449c9c028a16b5c249fb"
  }
]

Causa

Este error ocurre cuando realizas una solicitud al método Trigger a historical update for a link para un link que ha sido actualizado en los últimos 10 minutos.

Solución

Espera a que pase el período de enfriamiento antes de realizar otra solicitud para el mismo link. El mensaje de error indicará cuántos minutos necesitas esperar.

428 activation_required

[
  {
    "code": "activation_required",
    "message": "This user doesn't have web access activated yet.",
    "request_id": "3e7b283c6efa449c9c028a16b5c249jk"
  }
]

Causa

Este error ocurre cuando el usuario no ha activado su acceso a la banca por internet.

Solución

Pide al usuario que primero active su acceso a la banca por internet y luego pídeles que conecten su cuenta nuevamente.

428 token_required

[
  {
    "code": "token_required",
    "message": "A MFA token is required by the institution to login",
    "request_id": "8c7b283c6efa449c9c028a16b5c249fa",
    "session": "2675b703b9d4451f8d4861a3eee54449",
    "expiry": 9600,
    "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
    "token_generation_data": {
      "instructions": "Use this code to generate the token",
      "type": "numeric",
      "value": "12345"
    }
  }
]

Causa

Este error ocurre cuando la institución requiere MFA para iniciar sesión.

Solución

Consulta nuestro artículo sobre cómo manejar MFA. Sin embargo, te recomendamos encarecidamente que uses nuestro Connect Widget ya que manejaremos este tipo de errores por ti y guiaremos a tu usuario a través de los pasos para proporcionar su token de autenticación.

Mensaje de error del widget

En el caso de que tu usuario ingrese incorrectamente su token (o el token que ingrese esté caducado) mientras usa el widget, se muestran los siguientes mensajes de error:

500 service_unavailable

[
  {
    "code": "service_unavailable",
    "message": "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution",
    "request_id": "4a7b283c6efa449c9c028a16b5c249fd"
  }
]

Causa

Este error ocurre cuando nosotros (Belvo) hemos encontrado un error interno del sistema (lo sentimos por eso).

Solución

Puedes intentar de nuevo más tarde. Si sigues recibiendo este error, contacta a nuestro equipo de soporte, asegurándote de incluir el request_id que recibes en el mensaje.

500 unexpected_error

[
  {
    "code": "unexpected_error",
    "message": "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution",
    "request_id": "4a7b283c6efa449c9c028a16b5c249fd"
  }
]

Causa

Este error ocurre cuando nosotros (Belvo) hemos encontrado un error interno del sistema (lo sentimos) o debido a una respuesta no soportada de la institución.

Este tipo de error puede ser intermitente o persistente.

Solución

Recomendamos que intentes realizar tu solicitud original un máximo de tres veces, en caso de que el problema sea intermitente.

Si el error sigue ocurriendo con la misma solicitud, contacta a nuestro equipo de soporte, asegurándote de incluir el request_id que recibes en el mensaje de error.

Mensaje de error del widget

Errores encontrados recientemente en la API de Iniciación de Pagos

Además de la lista estándar de errores, nuestra API de Iniciación de Pagos también devuelve errores adicionales llamados last_errors que son específicos del flujo de pago. Cuando una intención de pago falla o encuentra un error en algún punto del flujo de pago, se devuelve un mensaje last_error en la respuesta para proporcionarte información sobre lo que salió mal. Dependiendo del error específico, es posible que necesites pedirle a tu cliente que corrija su información de pago o que inicie el flujo de pago nuevamente.

1. invalid_credentials
2. invalid_token
3. login_error
4. login_two_factor_error
5. missing_token_registration
6. payment_error
7. session_expired
8. unauthorized_credentials

A continuación, te proporcionamos mensajes de ejemplo, causas del error y cómo solucionarlos.

invalid_credentials

[
    {
      "error_code": "invalid_credentials",
      "error_message": "Las credenciales enviadas son incorrectas, por favor intente de nuevo."
    }
]

Causa

Este error puede ocurrir cuando las credenciales que proporciona su cliente son incorrectas.

Solución

Por favor, verifique cuál es el siguiente paso en el proceso de intención de pago para completar la transacción. Puede hacer esto realizando una solicitud de Obtener detalles sobre un enlace de pago y verificando el campo next_step.

invalid_token

[
    {
      "error_code": "invalid_token",
      "error_message": "El token enviado es incorrecto o ha expirado, por favor intente de nuevo."
    }
]

Causa

Este error puede ocurrir cuando el token MFA que su cliente proporciona es inválido.

Solución

Por favor, verifique cuál es el siguiente paso en el proceso de intención de pago para completar la transacción. Puede hacer esto realizando una solicitud de Obtener detalles sobre un enlace de pago y verificando el campo next_step.

login_error

[
    {
      "error_code": "login_error",
      "error_message": "Error de inicio de sesión del proveedor"
    }
]

Causa

Este error puede ocurrir cuando algo inesperado sucede en el siguiente paso display_credentials_required.

Solución

Por favor, verifica cuál es el siguiente paso en el proceso de intención de pago para completar la transacción. Puedes hacerlo realizando una solicitud de Obtener detalles sobre un enlace de pago y revisando el campo next_step.

login_two_factor_error

[
    {
      "error_code": "login_two_factor_error",
      "error_message": "Error de autenticación de dos factores del proveedor"
    }
]

Causa

Este error puede ocurrir cuando algo inesperado sucede en el siguiente paso display_token_required.

Solución

Por favor, verifica cuál es el siguiente paso en el proceso de intención de pago para completar la transacción. Puedes hacer esto realizando una solicitud para obtener detalles sobre un enlace de pago y revisando el campo next_step.

missing_token_registration

[
    {
      "error_code": "missing_token_registration",
      "error_message": "El usuario no tiene un token configurado en el banco."
    }
]

Causa

Este error puede ocurrir cuando tu usuario no ha registrado un token MFA con su banco.

Solución

Por favor, verifica cuál es el siguiente paso en el proceso de intención de pago para completar la transacción. Puedes hacer esto realizando una solicitud para obtener detalles sobre un enlace de pago y revisando el campo next_step.

payment_error

[
    {
      "error_code": "payment_error",
      "error_message": "Error inesperado al confirmar el pago"
    }
]

Causa

Este error puede ocurrir cuando algo inesperado sucede durante el proceso de confirmación del pago.

Solución

Por favor, verifica cuál es el siguiente paso en el proceso de intención de pago para completar la transacción. Puedes hacer esto realizando una solicitud de Obtener detalles sobre un enlace de pago y revisando el campo next_step.

session_expired

[
    {
      "error_code": "session_expired",
      "error_message": "Bank session was not found"
    }
]

Causa

Este error ocurre cuando intentas enviar una solicitud PATCH después de que la sesión ya ha expirado (la sesión expira después de 10 minutos).

Solución

Por favor, verifica cuál es el siguiente paso en el proceso de intención de pago para completar la transacción. Puedes hacer esto realizando una solicitud de Obtener detalles sobre un enlace de pago y revisando el campo next_step.

unauthorized_credentials

[
    {
      "error_code": "unauthorized_credentials",
      "error_message": "Your credentials are not authorized. Please, contact the bank."
    }
]

Causa

Este error ocurre cuando el usuario no ha proporcionado las credenciales autorizadas correctas para iniciar sesión en su institución.

Solución

Por favor, verifica cuál es el siguiente paso en el proceso de intención de pago para completar la transacción. Puedes hacer esto realizando una solicitud de Obtener detalles sobre un enlace de pago y revisando el campo next_step.