Introdução

Erros são irritantes - nós sabemos. É por isso que temos artigos dedicados para cada erro em nosso DevPortal para ajudá-lo a resolvê-los. Dê uma olhada no erro abaixo ou simplesmente procure o código de erro que você está encontrando para ir direto às causas e soluções.

Códigos de Resposta

Usamos o seguinte código de status HTTP na resposta, dependendo do sucesso ou falha:

Erros da API do Belvo são retornados no formato JSON. Por exemplo, um erro pode ser assim:

[
  {
    "request_id": "a6e1c493d7a29d91aed4338e6fcf077d",
    "message": "Este campo é obrigatório.",
    "code": "required",
    "field": "link"
  }
]

Normalmente, uma resposta de erro terá os seguintes parâmetros:

• request_id: um ID único para a solicitação, você deve compartilhá-lo com a equipe de suporte do Belvo para investigações.
• message: descrição legível do erro.
• code: um código único para o erro. Verifique a tabela abaixo para ver como lidar com cada código de erro.
• field (opcional): O campo específico no corpo da solicitação que tem um problema.

Notas gerais sobre tratamento de erros

Aqui está nossa recomendação em termos de nova tentativa em caso de erros:

Erros 50x

Implemente uma retentativa automática com backoff exponencial de até cinco tentativas. Recomendamos que você use um intervalo base de três segundos com um fator de dois. Por exemplo, a primeira tentativa de retentativa deve ser após três segundos, a segunda tentativa de retentativa é após 6 segundos (2*3), a terceira tentativa de retentativa é após 12 segundos (2*6), a quarta tentativa de retentativa é após 24 segundos (2*12), e a quinta tentativa de retentativa é após 48 segundos (2*24).

Erros 40x

Você não deve tentar novamente fazer solicitações se receber uma resposta 40x, pois isso é um erro do cliente.

A única exceção é o erro "Too Many Sessions", pois isso significa que seu usuário final está acessando a conta de outro navegador ao mesmo tempo. Nesse caso, implemente a mesma política de repetição que com erros 50x.

400 activation_failed

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

Causa

Este erro ocorre quando a Belvo não conseguiu ativar automaticamente o acesso ao internet banking para o usuário devido a informações ausentes (por exemplo, o 🇲🇽 CVV ou 🇲🇽 NIP estavam ausentes ou foram fornecidos incorretamente).

Solução

Peça ao usuário para primeiro ativar o acesso ao internet banking (seja entrando em contato diretamente com o banco ou tentando fazer login na conta de internet banking) e, em seguida, peça para conectar a conta novamente.

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

Você está tentando registrar uma conta bancária fornecendo um valor que já está vinculado a uma conta bancária registrada no Belvo. Isso pode incluir:

• O identificador da chave PIX da conta bancária
• O número da conta bancária

{
  "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", // Chave Pix já registrada no 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" // Número da conta já registrado no Belvo.
     }
}

Solução

Faça uma solicitação para obter todas as contas bancárias para receber uma lista de todas as contas bancárias que você registrou, filtrando os resultados pelos últimos quatro dígitos da conta bancária para obter os detalhes.

400 blank

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

Causa

Você enviou uma solicitação com uma string vazia para um campo obrigatório. Por exemplo:

{
    "institution": "", // Este campo é obrigatório e não pode ser uma string vazia.
    "username": "bnk100",
    "password": "full",
}

Solução

• Verifique a mensagem de erro para ver qual campo você precisa fornecer. Se você não tiver certeza de qual informação fornecer ou o formato, basta verificar nossa documentação de referência da 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 erro pode ocorrer quando:

• Você tentou cancelar uma payment intent que não estava agendada.
• Você enviou sua solicitação de cancelamento após o horário limite de 23:59:00 (GMT-3) do dia anterior à data de liquidação agendada.

400 does_not_exist

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

Causa

Você enviou uma solicitação onde forneceu um valor que não existe no banco de dados da Belvo. Por exemplo:

{
    "institution": "narnia", // Esta instituição não existe no banco de dados da Belvo.
    "username": "bnk100",
    "password": "full"
}

Solução

Verifique a mensagem de erro para ver em qual campo você forneceu um valor incorreto. Então:

• Certifique-se de que não cometeu nenhum erro de digitação.
• Verifique se o valor que você está fornecendo deve estar presente em nosso banco de dados (por exemplo, se você fizer uma solicitação para um link que ainda não foi registrado, você receberá um erro).

400 duplicado

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

Causa

Este erro pode ocorrer quando:

• Você tentou criar um link que já foi associado à sua conta.
• Seu usuário tentou criar um link com uma conta que já conectou.

Solução

Você pode:

• Consultar seu banco de dados para encontrar o institution_user_id e verificar se o link associado id ainda é válido usando a solicitação Obter detalhes de um link. Se o status não for valid, então solicite ao seu usuário que atualize suas credenciais usando o Belvo widget no modo de atualização.
• Consultar seu banco de dados para encontrar o institution_user_id e usar o link associado id para excluir o link do banco de dados da Belvo usando a Solicitação de exclusão de link. Depois de excluir o link, você pode pedir ao seu usuário para conectar sua conta novamente.

400 null

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

Causa

Você fez uma solicitação sem fornecer dados em um campo obrigatório. Por exemplo:

{
    "institution": , // Este campo é obrigatório.
    "username": "bnk100",
    "password": "full",
}

Solução

Verifique a mensagem de erro para ver qual campo você precisa fornecer. Se você não tiver certeza de qual informação fornecer ou o formato, basta verificar nossa documentação de referência da API.

400 required

[
    {
        "field": "username",
        "request_id": "b9abda13c9afbbc64a265c6d4f937d06",
        "message": "This field is required.",
        "code": "required"
    }
]

[
    {
        "field": "amount",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "message": "This field is required.",
        "code": "required"
    }
]

Causa
Você enviou uma solicitação sem um campo obrigatório. Por exemplo:

{
    "institution": "erebor_mx_retails",
            // Quando você está registrando um novo link, deve fornecer um 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"
     },
           // Quando você está criando um link de pagamento, deve fornecer um valor de pagamento.
     "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
     "description": "Awesome training Sneaker",
     "provider": "payments_way"
}

Solução

• Verifique a mensagem de erro para ver qual campo você precisa fornecer. Se você não tiver certeza de qual informação fornecer ou o formato, basta verificar nossa documentação de referência da API.

400 institution_down

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

Causa

Este erro ocorre quando o site da instituição que você está tentando acessar está fora do ar devido a manutenção ou outros problemas, o que significa que a Belvo não consegue criar novos links ou recuperar novos dados.

Solução

Você pode tentar acessar a instituição novamente mais tarde. Certifique-se de assinar nossa Página de Status das Instituições para saber assim que uma instituição estiver indisponível.

Você pode remover uma instituição que atualmente não está disponível usando o parâmetro institutions na configuração de inicialização e omitindo a instituição da lista.

Mensagem de erro do widget

400 institution_inactive

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

Causa

Este erro ocorre quando nós (Belvo) desativamos a instituição em nossa API.

Solução

Você pode tentar novamente mais tarde, assim que a Belvo reativar a instituição.

400 institution_unavailable

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

Causa

Este erro ocorre quando o site da instituição que você está tentando acessar está fora do ar devido a manutenção ou outros problemas, o que significa que a Belvo não consegue criar novos links ou recuperar novos dados.

Solução

Você pode tentar acessar a instituição novamente mais tarde. Certifique-se de assinar nossa Página de Status das Instituições para saber assim que uma instituição estiver indisponível.

Você pode remover uma instituição que atualmente não está disponível usando o parâmetro institutions na configuração de inicialização e omitindo a instituição da lista.

Mensagem de erro do widget

400 inválido

[
    {
        "field": "date_to",
        "request_id": "a7ad9a4ad8b13f8f800f8f5b69c7856f",
        "message": "Date has wrong format. Use one of these formats instead: YYYY-MM-DD.",
        "code": "invalid"
    }
]

[
    {
        "field": "link",
        "request_id": "448f2b58fc88b2c5a9db6c9175494950",
        "message": "“YTZjMDA3YjktZTk5Yy00MDczLTgzNGItOGM3NzA1MTMyZGU3" is not a valid UUID.",
        "code": "invalid"
    }
]

[
    {
        "field": "payments_way",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "terminal_id": [
            {
                "message": "The terminal_id is invalid, try again or contact Belvo's support.",
                "code": "invalid"
            }
        ]
    }
]

[
    {
        "field": "payments_way",
        "request_id": "a0c3b0e58e58409d9b1d49de9be35a3d",
        "form_id": [
            {
                "message": "The form_id is invalid, try again or contact Belvo's support.",
                "code": "invalid"
            }
        ]
    }
]

[
    {
        "field": "resources",
        "request_id": "a7ad9a4ad8b13f8f800f8f5b69c7856f",
        "message": "The institution only supports the following resources: {1}, {2}",
        "code": "invalid"
    }
]

Causa

Você enviou uma solicitação onde forneceu um valor em um formato inválido. Isso pode incluir:

• O formato das credenciais de login está incorreto.
• O formato da data está incorreto.
• O UUID não é válido.
• O terminal_id não é válido.
• O form_id não é válido.
• Os recursos que você incluiu em fetch_resources não são suportados pela instituição.

Por exemplo:

{
    "link": "a6c007b9-e99c-4073-834b-8c7705132de7",
    "date_from": "2020-01-01",
    "date_to": "2020-02" // Aqui, o formato da data deve ser YYYY-MM-DD
}

{
    "link": "a6c007b9-e99c" // Aqui, o ID do link não é um UUID válido.
}

{
     "holder": {
          "type": "BUSINESS",
          "information": {
               "name": "Trusty documentation services"
          }
     },
     "providers": {
          "payments_way": {
               "terminal_id": "1200", // A Belvo fornece o terminal_id correto que você precisa para criar uma conta bancária.
               "form_id": "3211", // A Belvo fornece o form_id correto que você precisa para criar uma conta bancária.
          }
     },
}

Solução

Verifique a mensagem de erro para ver qual campo é inválido e por quê. Em seguida, se precisar de mais informações, consulte nossa documentação da API para saber qual é o formato válido para o campo.

400 invalid_choice

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

Causa
Você fez uma solicitação onde em um dos campos você forneceu um valor que não era válido (por exemplo, pode aceitar apenas certas strings, semelhante a um enum). Por exemplo:

{
    "institution": "erebor_mx_retail",
    "username": "bnk100",
    "password": "full",
    "access_mode": "Australia" // Este não é uma escolha válida, conforme a documentação afirma que é um enum: single ou recurrent
}

Solução

• Verifique a mensagem de erro para ver em qual campo você forneceu um valor incorreto. Em seguida, consulte nossa documentação para ver qual valor você deve fornecer para este campo.

400 invalid_credentials_storage

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

Causa
Você fez uma solicitação onde para um link recorrente você definiu o parâmetro credentials_storage como nostore ou para um intervalo de datas entre 1d a 365d.

{
    "institution": "tatooine_mx_fiscal",
    "username": "PFIS010101000",
    "password": "individual",
    "access_mode": "recurrent",
    "credentials_storage": "nostore" // Para links recorrentes, isso deve ser definido como store
}

Solução

• Se você deseja criar um link recorrente, altere o valor de credentials_storage para store.
• Se você deseja criar um link único e não armazenar credenciais, altere o access_mode para single.

400 invalid_fetch_resources

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

Causa
Você tentou criar um link onde definiu o parâmetro credentials_storage como nostore e não passou nenhum recurso no parâmetro fetch_resources. Para links onde não armazenamos credenciais, você deve passar pelo menos um recurso em fetch_resources.

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

Solução

Liste os recursos que você deseja recuperar no parâmetro fetch_resources. Por exemplo: "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 erro ocorre quando você tenta acessar uma conta, mas as credenciais do usuário não são mais válidas, resultando em um erro da instituição.

Solução

Peça ao seu usuário para fornecer suas credenciais atualizadas. Para facilitar, recomendamos fortemente que você use nosso Widget em Modo de Atualização.

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 erro ocorre quando você solicita rendimentos para um link dentro de um determinado intervalo de datas, no entanto, o período entre date_from e date_to é inferior a 90 dias.

Solução

Certifique-se de que o período entre date_from e date_to seja igual ou superior a 90 dias.

400 login_error

[
  {
    "code": "login_error",
    "message": "Credenciais inválidas fornecidas para login na instituição",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "Um token MFA é exigido pela instituição, mas ainda não é suportado pela Belvo.",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "Impossível fazer login, algo inesperado aconteceu ao entrar na instituição. Tente novamente mais tarde.",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "Login não tentado devido a credenciais inválidas",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "Credenciais ausentes para login na instituição",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "O acesso à conta do usuário foi proibido pela instituição",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "O acesso à conta do usuário foi proibido pela instituição",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

[
  {
    "code": "login_error",
    "message": "A conta do usuário está bloqueada, o usuário precisa contatar a instituição para desbloqueá-la",
    "request_id": "3e7b283c6efa449c9c028a16b5c249fd"
  }
]

Causa

Este erro pode ocorrer quando:

• as credenciais que seu usuário fornece estão incorretas ou ausentes.
• o token MFA que seu usuário fornece não é suportado pela Belvo.
• há um problema com a instituição que impede logins.
• a conta do usuário está bloqueada ou o usuário não tem permissão para acessar seu internet banking.

Solução

• Peça ao seu usuário para fornecer suas credenciais corretas ou token MFA. Use nosso widget para facilitar ainda mais (nós fazemos todo o trabalho pesado para você).
• Peça ao seu usuário para confirmar com seu banco se a conta está ativa e se não está bloqueada.
• Se houver um problema com a instituição, tente fazer login em um momento posterior.

400 max_digits

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

Causa
Você enviou uma solicitação com o formato de quantia incorreto. Por exemplo:

{
     "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"
}

Solução

Verifique a mensagem de erro para ver por que o formato da quantia é inválido. Se você não tiver certeza de quais informações fornecer ou o formato, basta verificar nossa documentação de referência da API para saber qual é o formato válido para o 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
Você enviou uma solicitação com o formato de quantia incorreto. Por exemplo:

{
     "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"
}

Solução

Verifique a mensagem de erro para ver por que o formato da quantia é inválido. Se você não tiver certeza de quais informações fornecer ou o formato, basta verificar nossa documentação de referência da API para saber qual é o formato válido para o 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
Você enviou uma solicitação com o formato de valor incorreto. Por exemplo:

{
     "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"
}

Solução

Verifique a mensagem de erro para ver por que o formato do valor é inválido. Se você não tiver certeza sobre quais informações fornecer ou o formato, basta verificar nossa documentação de referência da API para saber qual é o formato válido para o campo.

400 not_a_list

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

Causa
Você enviou uma solicitação onde, em vez de enviar um array de dados, você enviou apenas uma lista. Por exemplo:

{
    "fetch_resources": "ACCOUNTS,OWNERS", // Aqui, fetch_resources deve ser um array de valores
}

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

Solução

Verifique sua solicitação JSON e consulte nossa documentação para ver qual campo deve ser um 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
Você enviou uma solicitação com JSON inválido. Por exemplo:

{
    "link": "a6c007b9-e99c-4073-834b-8c7705132de7", // Aqui, você não deve ter uma vírgula no final em sua solicitação
}

Solução

Verifique o payload JSON (talvez você esteja apenas esquecendo uma vírgula ou aspas) e tente novamente.

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 erro ocorre quando você tenta retomar uma sessão de request que já expirou. Isso geralmente acontece porque o usuário demorou muito para fornecer seu token de autenticação.

Para requests que exigem um token, há um período de tempo em que o usuário pode fornecer seu token. O período varia de instituição para instituição. Você pode verificar quanto tempo o usuário tem para inserir seu token usando o parâmetro expiry na resposta 428 token_required.

Solução

Infelizmente, você precisará iniciar todo o processo de login com seu usuário novamente.

Mensagem de erro do widget

400 session_expired_ob

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

Causa

Você pode receber este erro devido aos seguintes motivos:

1. O access_token que você gerou não foi usado dentro do período de expiração de 10 minutos.
2. Em vez de gerar um novo access_token para o widget para o usuário dado, você usou um access_token gerado para outro usuário que já criou um link usando o widget.
3. Seu usuário não clicou no botão Ir para a instituição no widget dentro de 60 segundos após a tela aparecer.

Solução

Infelizmente, você precisará iniciar o processo do widget com seu usuário novamente. Por favor, certifique-se de que você:

1. Garanta que você use o access_token para gerar o widget assim que ele for criado. Se passarem 10 minutos ou mais, você precisará criar um novo access_token.
2. Garanta que você sempre crie um novo access_token para cada usuário.
3. Nossa equipe de UX está melhorando o fluxo para solicitar ao usuário que continue o fluxo dentro dos 60 segundos alocados.

Mensagem de erro do 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 erro ocorre quando:

• um usuário está tentando fazer login na sua instituição via Belvo enquanto já está logado na sua instituição em um navegador web ou aplicativo móvel.
• você faz uma solicitação de informações enquanto a Belvo está extraindo dados da instituição para esse usuário.

Solução

Tente:

• Informar seu usuário para fechar suas sessões web e de aplicativo para a instituição em questão.
• Aguardar 120 segundos e tentar novamente sua solicitação, garantindo que a Belvo tenha terminado o processo de extração de dados.

Mensagem de erro do widget

400 unavailable_data

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

Causa

Este erro ocorre quando sua solicitação foi corretamente formada e enviada, no entanto, a instituição não retornou nenhum dado para sua solicitação.

Solução

Recomendamos primeiro verificar nossa Página de Status da Instituição para ver se há algum incidente com a instituição que está impedindo a extração de dados. Se não houver incidentes ativos para a instituição, você pode tentar novamente a solicitação. Se continuar recebendo este erro, entre em contato com nossa equipe de suporte, certificando-se de incluir o request_id que você recebe na mensagem.

400 unconfirmed_link

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

Causa

Este erro ocorre quando você tenta acessar um link que foi pausado anteriormente (e, como tal, não está ativo agora).

Solução

Peça ao seu usuário para fornecer um token MFA através do nosso widget em modo de atualização para completar um primeiro login. Após o usuário completar o processo com sucesso, você poderá recuperar os dados.

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 erro ocorre quando:

• Você tenta acessar alguma operação de dados que a Belvo não suporta para uma instituição. Por exemplo, tentar acessar o recurso Transactions para instituições Fiscais.
• Você faz uma solicitação que requer que alguma lógica de negócios seja concluída. Por exemplo, ao usar o parâmetro fetch_resources na criação de um único link, você também deve definir fetch_historical como true

Solução

Certifique-se de que:

• A operação de recurso (por exemplo, solicitar Transactions) é suportada para essa instituição.
• Sua solicitação cumpre toda a lógica de negócios necessária.

Mensagem de erro do widget

400 validation_error

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

Causa

Você enviou uma solicitação onde:

• As credenciais fornecidas não corresponderam aos campos esperados, levando a um erro de validação de campo da instituição.

Por exemplo:

{
    "link": "a6c007b9-e99c-4073-834b-8c7705132de7",
    "date_from": "2020-01-01",
    "date_to": "2021-03-30" // Entre date_from e date_to há mais de 365 dias
}

Solução

Obtenha os detalhes da instituição usando nosso endpoint de Instituições e verifique o objeto form_fields para obter informações sobre quais campos precisam ser fornecidos e seu formato.

401 authentication_failed

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

Causa

Este erro ocorre quando você tenta fazer uma chamada de API usando credenciais incorretas da API da Belvo (ou sua chave secreta ou senha secreta, ou ambos, estão incorretos).

Solução

Verifique as credenciais que você está usando em comparação com as do seu dashboard. Talvez você esteja usando suas credenciais de sandbox para acessar dados de produção (ou vice-versa). Nota: Se você não tiver certeza sobre sua secretPassword, verifique o e-mail de confirmação que você recebeu da 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 erro ocorre quando o seu usuário removeu contas associadas ao consentimento que forneceram. Por exemplo, quando o seu usuário gerou o consentimento pela primeira vez, ele tinha uma conta corrente e uma conta de empréstimo na instituição, mas desde então fechou essas contas.

Solução

Entre em contato com o seu usuário para confirmar se ele removeu a conta e peça para gerar um novo consentimento na instituição atual.

403 access_to_production_denied

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

Causa

Este erro ocorre quando você tenta acessar o ambiente de produção da Belvo sem as permissões corretas.

Solução
Entre em contato com nossa equipe de vendas para solicitar acesso ao ambiente de produção.

403 access_to_resource_denied

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

Causa

Este erro ocorre quando você tenta acessar um recurso da Belvo sem as permissões corretas.

Solução
Entre em contato com nossa equipe de vendas para solicitar acesso a este recurso.

403 Forbidden

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

<center><h1>403 Forbidden</h1></center>

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

</body></html>

Causa

Este erro ocorre quando você faz um grande volume de solicitações (mais de 80 solicitações em 30 segundos) em rápida sucessão a partir do mesmo endereço IP.

Solução

Se você espera ter consistentemente grandes volumes de chamadas do mesmo endereço IP, por favor, entre em contato com nossa equipe de Sucesso do Cliente.

403 permission_denied

Causa

Este erro ocorre quando nós (Belvo) estamos proibidos de acessar um determinado recurso na instituição, ou você excedeu seu limite de solicitações.

Solução
Se você conseguiu acessar este recurso anteriormente, tente novamente mais tarde. Nós (Belvo) monitoramos ativamente esses erros e designamos engenheiros para corrigir a situação o mais rápido possível.

403 quota_limit_reached

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

Causa

Este erro ocorre quando você excedeu o limite de Link no ambiente de desenvolvimento.

Solução

Para continuar usando o ambiente de desenvolvimento, você precisa excluir Links suficientes para ficar abaixo do limite do ambiente.

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

Você fez uma solicitação onde você:

• forneceu a URL errada.
• usou um ID (para um link, conta, transação, etc.) que não está associado à sua conta Belvo.
• fez uma solicitação para um link onde o credentials_storage foi definido como no_store ou 30d, e a Belvo não possui mais essas credenciais armazenadas para recuperar informações.

Solução

Certifique-se de que:

• Você está usando a URL correta (verifique erros de digitação e nossa documentação de referência da API).
• Você está usando um ID que está associado à sua conta Belvo.

No caso em que o link foi criado com o credentials_storage definido como no_store ou 30d, você precisará pedir ao usuário para reconectar sua conta.

405 method_not_allowed

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

Causa

Este erro ocorre quando você tenta usar um método da API que não é permitido para o recurso dado (por exemplo, uma solicitação PATCH para endpoints Fiscais).

Solução

Verifique quais métodos são permitidos para o recurso dado em nossa Documentação de Referência da 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

A Belvo tem um limite em relação ao tempo necessário para fazer login, recuperar dados da conta e fazer logout, que é definido em cinco (5) minutos. Um timeout ocorre quando há uma quantidade muito grande de dados e tudo não pôde ser obtido dentro do tempo alocado.

Por exemplo, se uma conta tiver mais de 2000 transações por conta por mês, você pode receber um erro request_timeout.

Solução

Quando ocorre um timeout, nossa API ainda salva o máximo de dados que conseguiu recuperar. Assim, você pode tentar fazer a mesma solicitação novamente e recuperar todos os dados com sucesso.

Se você continuar recebendo erros de timeout para vários links, ou três timeouts para o mesmo link, reporte à Belvo e forneça os request_ids.

Mensagem de erro do widget

428 activation_required

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

Causa

Este erro ocorre quando o usuário não ativou o acesso ao seu internet banking.

Solução

Peça ao usuário para primeiro ativar o acesso ao seu internet banking e, em seguida, peça para conectar sua conta novamente.

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 erro ocorre quando a instituição requer MFA para fazer login.

Solução

Veja nosso artigo sobre como lidar com MFA. No entanto, recomendamos fortemente que você use nosso Connect Widget, pois lidaremos com esses tipos de erros para você e guiaremos seu usuário pelos passos para fornecer seu token de autenticação.

Mensagem de erro do widget

No caso de seu usuário inserir incorretamente seu token (ou o token que ele insere estiver expirado) enquanto usa o widget, as seguintes mensagens de erro são exibidas:

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 erro ocorre quando nós (Belvo) encontramos um erro interno do sistema (desculpe por isso).

Solução

Você pode tentar novamente mais tarde. Se continuar recebendo este erro, entre em contato com nossa equipe de suporte, certificando-se de incluir o request_id que você recebe na mensagem.

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 erro ocorre quando nós (Belvo) encontramos um erro interno do sistema (desculpe por isso) ou devido a uma resposta não suportada da instituição.

Este tipo de erro pode ser intermitente ou persistente.

Solução

Recomendamos que você tente fazer sua solicitação original no máximo três vezes, caso o problema seja intermitente.

Se o erro continuar ocorrendo com a mesma solicitação, entre em contato com nossa equipe de suporte, certificando-se de incluir o request_id que você recebe na mensagem de erro.

Mensagem de erro do widget

Últimos erros encontrados na API de Iniciação de Pagamentos

Além da lista padrão de erros, nossa API de Iniciação de Pagamentos também retorna erros adicionais chamados last_errors que são específicos do fluxo de pagamento. Quando uma intenção de pagamento falha ou encontra um erro em algum ponto do fluxo de pagamento, uma mensagem last_error é retornada na resposta para fornecer informações sobre o que deu errado. Dependendo do erro específico, pode ser necessário solicitar ao seu cliente que corrija suas informações de pagamento ou inicie o fluxo de pagamento novamente.

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

Abaixo, fornecemos mensagens de exemplo, causas para o erro e como solucioná-los.

invalid_credentials

[
    {
      "error_code": "invalid_credentials",
      "error_message": "As credenciais enviadas estão incorretas, por favor, tente novamente."
    }
]

Causa

Este erro pode ocorrer quando as credenciais que seu cliente fornece estão incorretas.

Solução

Por favor, verifique qual é o próximo passo no processo de intenção de pagamento para completar a transação. Você pode fazer isso realizando uma solicitação para obter detalhes sobre um link de pagamento e verificando o campo next_step.

invalid_token

[
    {
      "error_code": "invalid_token",
      "error_message": "The token sent is incorrect or has expired, please try again."
    }
]

Causa

Este erro pode ocorrer quando o token MFA que seu cliente fornece é inválido.

Solução

Por favor, verifique qual é o próximo passo no processo de intenção de pagamento para completar a transação. Você pode fazer isso fazendo uma solicitação de Obter detalhes sobre um link de pagamento e verificando o campo next_step.

login_error

[
    {
      "error_code": "login_error",
      "error_message": "Erro de login do provedor"
    }
]

Causa

Este erro pode ocorrer quando algo inesperado acontece na próxima etapa display_credentials_required.

Solução

Por favor, verifique qual é a próxima etapa no processo de intenção de pagamento para completar a transação. Você pode fazer isso realizando uma solicitação para obter detalhes sobre um link de pagamento e verificando o campo next_step.

login_two_factor_error

[
    {
      "error_code": "login_two_factor_error",
      "error_message": "Provider login two factor error"
    }
]

Causa

Este erro pode ocorrer quando algo inesperado aconteceu na próxima etapa display_token_required.

Solução

Por favor, verifique qual é a próxima etapa no processo de intenção de pagamento para completar a transação. Você pode fazer isso realizando uma solicitação para obter detalhes sobre um link de pagamento e verificando o campo next_step.

missing_token_registration

[
    {
      "error_code": "missing_token_registration",
      "error_message": "The user has no token configured in the bank."
    }
]

Causa

Este erro pode ocorrer quando o usuário não registrou um token MFA com seu banco.

Solução

Por favor, verifique qual é o próximo passo no processo de intenção de pagamento para completar a transação. Você pode fazer isso fazendo uma solicitação para obter detalhes sobre um link de pagamento e verificando o campo next_step.

payment_error

[
    {
      "error_code": "payment_error",
      "error_message": "Erro inesperado ao confirmar o pagamento"
    }
]

Causa

Este erro pode ocorrer quando algo inesperado acontece durante o processo de confirmação do pagamento.

Solução

Por favor, verifique qual é o próximo passo no processo de intenção de pagamento para completar a transação. Você pode fazer isso fazendo uma Solicitação para obter detalhes sobre um link de pagamento e verificando o campo next_step.

session_expired

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

Causa

Este erro ocorre quando você tenta enviar uma solicitação PATCH após a sessão já ter expirado (a sessão expira após 10 minutos).

Solução

Por favor, verifique qual é o próximo passo no processo de intenção de pagamento para completar a transação. Você pode fazer isso fazendo uma solicitação Obter detalhes sobre um link de pagamento e verificando o campo next_step.

unauthorized_credentials

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

Causa

Este erro ocorre quando o usuário não forneceu as credenciais autorizadas corretas para fazer login na sua instituição.

Solução

Por favor, verifique qual é o próximo passo no processo de intenção de pagamento para completar a transação. Você pode fazer isso fazendo uma solicitação para obter detalhes sobre um link de pagamento e verificando o campo next_step.