Erros e Validações

Aprenda sobre os diferentes status e erros que você pode enfrentar ao usar a API do Pluggy.

Ao conectar um Item, se a conexão for bem-sucedida e todos os produtos forem recuperados corretamente, GET /items/:id retornará algo como isto:

{
  "id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
  "status": "UPDATED",
  "executionStatus": "SUCCESS",
  "lastUpdatedAt": "2024-09-27T14:51:46.216Z",
  "error": null,
  "statusDetail": null
}

Se o status de execução for SUCCESS, isso significa que todos os produtos (contas, transações, etc) foram recuperados corretamente da instituição e estão prontos para serem acessados.

Item falhou ao fazer login#

Ao criar ou atualizar um item, podemos falhar ao fazer login, o que retorna um status LOGIN_ERROR:

{
  "id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
  "status": "LOGIN_ERROR",
  "executionStatus": "INVALID_CREDENTIALS",
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Credenciais inválidas."
  },
  "statusDetail": null
}

Aqui, nenhum produto foi recuperado, e não podemos tentar a conexão novamente: precisamos que o usuário atualize suas credenciais.

Item falhou ao começar a recuperar produtos#

Existem situações em que não conseguimos recuperar nenhum produto (por exemplo, a instituição está fora do ar, a instituição nos informa que há outra sessão ativa e nos expulsa, etc), mas isso não é necessariamente um problema com o login. Nesses casos, o item terá o status OUTDATED:

{
  "id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
  "status": "OUTDATED",
  "executionStatus": "CONNECTION_ERROR",
  "error": {
    "code": "CONNECTION_ERROR",
    "message": "Erro de conectividade, por favor, tente novamente."
  },
  "statusDetail": null
}

Quando a instituição está enfrentando uma instabilidade, o executionStatus será SITE_NOT_AVAILABLE, no entanto, quando é um erro inesperado do nosso lado, o executionStatus será ERROR ou CONNECTION_ERROR.

Você pode tentar atualizar o item novamente para ver se o problema persiste (por exemplo, o banco pode estar instável pela manhã, mas se recuperar mais tarde durante o dia).

Se você tiver auto-sync, itens OUTDATED são tentados automaticamente até 5 vezes, com 1 hora entre cada tentativa. Se falhar 5 vezes, ele é removido do auto-sync.

Item falhou ao recuperar um produto específico#

Às vezes, acessamos a instituição corretamente, mas um determinado produto não pode ser recuperado. Isso resultará em um status de UPDATED com um status de execução de PARTIAL_SUCCESS. O campo statusDetail terá informações sobre quais produtos falharam.

{
  "id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
  "status": "UPDATED",
  "executionStatus": "PARTIAL_SUCCESS",
  "error": null,
  "statusDetail": {
    "accounts": {
      "warnings": [],
      "isUpdated": true,
      "lastUpdatedAt": "2024-01-23T22:39:55.622Z"
    },
    "transactions": {
      "warnings": [],
      "isUpdated": false,
      "lastUpdatedAt": "2024-01-21T22:39:55.622Z"
    },
    "creditCards": null
  }
}

Você também pode tentar novamente nesses casos para ver se o problema persiste. O auto-sync não tenta novamente PARTIAL_SUCCESS.

Entendendo Avisos

Quando produtos falham ou têm problemas, o statusDetail inclui avisos que explicam o porquê. Aprenda mais sobre avisos e como lidar com eles no guia Warnings & Status Codes.

O objeto de Erro#

O seguinte tipo representa a estrutura completa do erro:

type ExecutionErrorResult = {
  code: ExecutionErrorCodes
  message: string
  providerMessage?: string
  attributes?: Record<string, string>
}

Com certos erros, o objeto de erro é retornado com uma chave attributes com informações adicionais necessárias para futuras execuções:

{
  "error": {
    "code": "USER_AUTHORIZATION_PENDING",
    "message": "O usuário precisa conceder as permissões necessárias para sua conta.",
    "attributes": {
      "deviceNickname": "123456789"
    }
  }
}

Quando o código de erro é ACCOUNT_NEEDS_ACTION, usamos um campo chamado providerMessage em português, com qualquer mensagem de alerta relevante da instituição:

{
  "error": {
    "code": "ACCOUNT_NEEDS_ACTION",
    "message": "A conta precisa de uma ação manual do usuário.",
    "providerMessage": "Sua senha deve ser alterada"
  }
}

O campo providerMessage é a mensagem exata retornada pela Instituição Financeira ao encontrar um erro, sem qualquer tratamento. Dessa forma, o usuário pode ter uma mensagem amigável e clara sobre o porquê isso está acontecendo. Não fornecemos uma lista dessas mensagens, pois estão sujeitas a alterações pela IF.

Tratando erros#

A lógica de tratamento de erros, em geral, pode parecer algo assim:

• Se executionStatus for SUCCESS
  • Busque todos os produtos (transações, contas, etc)
  • Verifique os avisos (se houver) para ver informações sobre como os dados podem ser melhorados.
• Se executionStatus for PARTIAL_SUCCESS
  • Busque todos os produtos isUpdated: true
  • Gere um alerta interno se for um produto crítico (por exemplo, TRANSACTIONS) ou adicione um alerta para o usuário.
  • Verifique os avisos (se houver) para ver informações sobre por que o produto falhou.
• Se o status for LOGIN_ERROR (Open Finance não requer tratamento desse caso):
  • Não busque nenhum produto
  • Solicite ao usuário que insira suas credenciais novamente
• Se o status for OUTDATED:
  • Não busque nenhum produto
  • Gere um alerta interno ou adicione um alerta para o usuário

Para conectores diretos, todos os casos de erro estão descritos aqui.

Casos de erro do Open Finance#

Para o Open Finance, há apenas um subconjunto de possíveis casos de erro, conforme segue, dividido por status e executionStatus:

• LOGIN_ERROR:
  • INVALID_CREDENTIALS: o CPF/CNPJ é inválido
  • USER_AUTHORIZATION_NOT_GRANTED: o usuário rejeitou o consentimento durante o fluxo de autorização
  • USER_AUTHORIZATION_REVOKED: o usuário revogou o consentimento de seu banco
• OUTDATED:
  • USER_INPUT_TIMEOUT: o usuário nunca terminou o fluxo de autorização
  • SITE_NOT_AVAILABLE: a instituição está atualmente instável
  • ERROR/CONNECTION_ERROR: ocorreu um erro inesperado ao acessar a instituição
• UPDATED:
  • PARTIAL_SUCCESS: falha ao recuperar um produto, provavelmente porque o limite mensal foi atingido ou porque a instituição tem uma instabilidade temporária nesse produto.

Validações de Criação de Item#

As validações na API do Pluggy são muito importantes. Elas são usadas para evitar a execução de conectores com parâmetros inválidos e para criar conexões de item que não serão sincronizadas devido a credenciais ou parâmetros inválidos. Ao criar ou atualizar um item, as validações serão executadas para esse item com base nas credenciais do conector.

Este é um exemplo de uma resposta de validação ao criar um item:

// HTTP 400
{
  "message": "Os parâmetros do conector não correspondem às regras de validação",
  "errors": [
    {
      "code": "002",
      "message": "o comprimento do parâmetro usuário deve ser de pelo menos 6.",
      "parameter": "user"
    },
    {
      "code": "002",
      "message": "o comprimento do parâmetro senha deve ser de pelo menos 6.",
      "parameter": "password"
    }
  ]
}

Erros de rejeição de atualização#

Existem alguns casos em que um item não pôde ser atualizado devido ao estado do item: