# Introdução

Códigos de Erro V1 vs V2
Nossa API de Pagamentos fornece detalhes de erro em diferentes parâmetros dependendo da versão que você usa:

- **Autorizações de Pagamento & Cobranças (V2):** Usa `status_reason_code` (em `MAIÚSCULAS`) e `status_reason_message`. A tabela abaixo lista todos os possíveis códigos `MAIÚSCULAS` para esta versão.
- **Intenções de Pagamento & Cobranças (V1):** Usa `failure_code` (em `minúsculas`) e `failure_message`. Por exemplo, `beneficiary_bank_revoked_authorization` ou `invalid_pix_key`.


Quando uma Autorização de Pagamento ou uma Cobrança associada (V2) encontra um erro, a Belvo atualiza o `status` do recurso fornecido. Além disso, a Belvo fornece informações detalhadas sobre a mudança de status nos parâmetros `status_reason_code` e `status_reason_message` para ajudá-lo a entender o que deu errado.

Abaixo está uma tabela abrangente de todos os possíveis valores de `status_reason_code` e suas mensagens correspondentes:

| Código  | Mensagem (Apenas EN) |
|  --- | --- |
| `ACCOUNT_NOT_ALLOWED` | The payer account does not allow payments. |
| `AMOUNT_OVER_LIMIT` | O valor excede o limite máximo para a conta. |
| `AUTHORIZATION_EXPIRED` | A Autorização de Pagamento não foi concluída dentro do período permitido. |
| `BANK_USER_MISMATCH` | O usuário bancário autenticado difere do usuário pagador. |
| `BENEFICIARY_ACCOUNT_BLOCKED` | A conta bancária do beneficiário está bloqueada. |
| `BENEFICIARY_ACCOUNT_CLOSED` | A conta bancária do beneficiário está encerrada. |
| `BENEFICIARY_ACCOUNT_ERROR` | A Cobrança não pôde ser concluída devido a um erro inesperado na conta do beneficiário. |
| `BENEFICIARY_ACCOUNT_NUMBER_INVALID` | O número da conta bancária do beneficiário é inválido ou inexistente. |
| `BENEFICIARY_ACCOUNT_TYPE_INVALID` | O tipo de conta bancária do beneficiário não permite este tipo de ação. |
| `BENEFICIARY_ACCOUNT_TYPE_NOT_SUPPORTED` | O tipo de transação não é suportado ou autorizado pela conta do beneficiário. |
| `BENEFICIARY_BANK_REJECTED_CHARGE` | A Cobrança foi rejeitada pela instituição do beneficiário. |
| `BENEFICIARY_CANCELLED_RECURRING_PAYMENT` | O beneficiário cancelou o agendamento de pagamento recorrente. |
| `BENEFICIARY_IDENTIFIER_INVALID` | O CPF ou CNPJ do beneficiário está incorreto. |
| `BENEFICIARY_IDENTIFIER_MISMATCH` | O CPF ou CNPJ do beneficiário não corresponde ao titular da conta. |
| `BENEFICIARY_REVOKED_AUTHORIZATION` | O beneficiário revogou a Autorização de Pagamento. |
| `CANCELLATION_NOT_ALLOWED_CHARGE` | A Cobrança está em um status que não permite cancelamento. |
| `CANCELLATION_NOT_ALLOWED_PAYMENT_AUTHORIZATION` | A Autorização de Pagamento está em um status que não permite cancelamento. |
| `CANCELLED_WHILE_PENDING` | A Cobrança foi cancelada enquanto estava no status PENDENTE. |
| `CANCELLED_WHILE_SCHEDULED` | A Cobrança foi cancelada enquanto estava no status AGENDADO. |
| `CHARGE_EXCEEDS_AUTHORIZED_AMOUNT` | O valor da Cobrança excedeu os limites definidos na Autorização de Pagamento. |
| `CHARGE_PERIOD_LIMIT_REACHED` | O número de Cobranças excedeu o total permitido para o período, conforme definido na Autorização de Pagamento. |
| `CHARGE_SETTLEMENT_FAILED` | Ocorreu um erro ao processar a liquidação da Cobrança. |
| `CHARGE_SETTLEMENT_TIMEOUT` | A Cobrança não pôde ser concluída devido a um timeout. |
| `DUPLICATE_BENEFICIARY_CHARGE` | Uma Cobrança duplicada foi detectada para o mesmo beneficiário. |
| `FRAUD_SUSPECTED` | A Cobrança foi rejeitada devido a suspeita de fraude. |
| `IDENTIFIER_MISMATCH` | O Identificador de Cliente da Autorização de Pagamento não corresponde ao identificador do titular da conta na instituição. |
| `INSUFFICIENT_FUNDS` | Fundos insuficientes na conta bancária do pagador. |
| `INSUFFICIENT_PERMISSION` | O pagador associado à Autorização de Pagamento não tem permissões suficientes para realizar ações para a conta. |
| `INVALID_AMOUNT_QRCODE` | O valor enviado não é válido para o QR Code inserido, ou o QR Code usado para iniciar o pagamento não é válido. |
| `INVALID_CHARGE` | Esta Cobrança não pode ser processada porque expirou, passou da data de vencimento ou está em um status inválido. |
| `INVALID_PAYMENT_AUTHORIZATION` | A Autorização de Pagamento está em um estado final e não pode ser usada para novas Cobranças. |
| `NO_REASON_PROVIDED` | Nenhuma razão de erro foi fornecida pela instituição. |
| `OPEN_FINANCE_NETWORK_FAILURE` | Um dos seguintes:- O pagamento foi recusado pelo sistema SPI.
- Houve uma falha na infraestrutura do SPI.
- Houve uma falha na infraestrutura do DICT.
- Houve uma falha na infraestrutura do PKI.
- Houve uma falha na infraestrutura do PSP receptor.
- Houve uma falha na infraestrutura do titular da conta.

 |
| `OUTSIDE_ALLOWED_TIMEFRAME` | A tentativa de agendamento foi feita fora do período permitido e não foi aceita pela instituição. |
| `PARTIALLY_ACCEPTED_PAYMENT_AUTHORIZATION` | A Autorização de Pagamento deve ser aceita por todos os titulares da conta. |
| `PAYER_ACCOUNT_TIMEOUT_ERROR` | A liquidação da Cobrança falhou devido a um timeout na conta do pagador. |
| `PAYER_BLOCKED_BY_REGULATORY_REASON` | A Cobrança foi rejeitada porque o pagador está bloqueado por razões regulatórias. |
| `PAYER_REVOKED_AUTHORIZATION` | O pagador revogou a Autorização de Pagamento. |
| `PAYMENT_CONSENT_MISMATCH` | As informações fornecidas para esta Cobrança diferem da Autorização de Pagamento associada. |
| `PAYMENT_NOT_COMPLETED_CONSENT_EXPIRED` | A Cobrança não foi concluída dentro do tempo autorizado. |
| `PAYMENT_REFUSED_BY_HOLDER` | O pagador recusou a Cobrança. |
| `PAYMENT_SCHEDULING_FAILURE` | A instituição falhou ao agendar o pagamento. |
| `REJECTED_UNKNOWN` | A Autorização de Pagamento foi rejeitada por razões desconhecidas. |
| `REVOKED_PAYMENT_AUTHORIZATION` | A Cobrança está associada a uma Autorização de Pagamento que foi revogada. |
| `REVOKED_UNKNOWN` | A Autorização de Pagamento foi revogada por razões desconhecidas. |
| `SAME_ORIGIN_DESTINATION_ACCOUNTS` | As contas do beneficiário e do pagador são as mesmas. |
| `SETTLEMENT_LIMIT_REACHED` | O número máximo de tentativas de liquidar a Cobrança na instituição foi alcançado. |
| `SYSTEM_ERROR` | A solicitação não pôde ser concluída devido a um erro de sistema. |
| `UNEXPECTED_ERROR` | Um dos seguintes:- Ocorreu um erro inesperado ao processar a Cobrança.
- Ocorreu um erro inesperado ao processar a Autorização de Pagamento.

 |
| `USER_DAILY_LIMIT_REACHED` | O limite diário máximo do usuário para a conta foi alcançado. |
| `USER_PERIOD_LIMIT_REACHED` | O limite máximo do usuário para a conta e para o período foi alcançado. |
| `USER_REJECTED` | O pagador rejeitou a Autorização de Pagamento. |


## Códigos de falha V1 (Payment Intents e Charges)

A tabela acima lista os valores de `status_reason_code` da V2. Payment Intents e Charges (V1) retornam `failure_code` e `failure_message` em `lowercase` em vez disso—por exemplo, em webhooks de V1 `PAYMENT_INTENTS` com `webhook_code` `STATUS_UPDATE`.

| Código de falha  | Mensagem de falha (somente EN) | Quando pode ocorrer |
|  --- | --- | --- |
| `invalid_pix_key` | The provided Pix Key is invalid. | Payment Intent `STATUS_UPDATE` quando a Chave Pix do beneficiário no pagamento não pode ser validada. |