codeDescription do envelope de erro, os executionStatus de
erro de uma execução de Item e os códigos de item.error com a resolução recomendada.
Para o formato do envelope, os erros de validação errors[] e o que enviar num ticket, veja
Erros.
Status HTTP e significado
Todocode no envelope espelha o status HTTP.
Semântica crítica 403 vs. 401: falha de autenticação em
POST /connect_token aparece como
403, não 401. Trate um 403 desse endpoint como “renove a apiKey via POST /auth e tente de
novo”, não como problema de permissão.codeDescription conhecidos
O codeDescription é o discriminador estável (SCREAMING_SNAKE_CASE) no qual os clientes devem
ramificar. Os valores devem casar exatamente.
executionStatus de erro
O executionStatus é o estado fino da última execução de um Item. Os valores finais de erro
são:
Há também os valores finais de sucesso
SUCCESS (todos os produtos coletados) e
PARTIAL_SUCCESS (alguns produtos falharam — inspecione statusDetail por produto). O
PARTIAL_SUCCESS aparece, por exemplo, quando um limite mensal da rede de Open Finance é atingido
(aviso 423). Veja Limites do Open Finance.Códigos de item.error
Entregues via webhook item/error e em GET /items/{id} → error.code. Cada um tem uma resolução
recomendada.
INVALID_CREDENTIALS — usuário/senha errados
INVALID_CREDENTIALS — usuário/senha errados
O usuário digitou usuário ou senha incorretos. Resolução: envie o usuário pelo update mode
do widget com o mesmo
itemId para reinserir as credenciais.INVALID_CREDENTIALS_MFA — token MFA errado/expirado
INVALID_CREDENTIALS_MFA — token MFA errado/expirado
Token MFA incorreto ou expirado. Resolução: reinicie o MFA no update mode.
ALREADY_LOGGED_IN — sessão presa em outro dispositivo
ALREADY_LOGGED_IN — sessão presa em outro dispositivo
A sessão na instituição está retida por outro dispositivo. Resolução: peça ao usuário para
sair (logout) dos outros dispositivos e tente novamente.
ACCOUNT_LOCKED — conta bloqueada na instituição
ACCOUNT_LOCKED — conta bloqueada na instituição
A instituição bloqueou a conta após muitas falhas. Resolução: intervenção manual do usuário no
app do banco; não é recuperável via API.
ACCOUNT_NEEDS_ACTION — ação exigida no banco
ACCOUNT_NEEDS_ACTION — ação exigida no banco
A instituição exige que o usuário aceite termos ou atualize o perfil. Resolução: o usuário faz
login no app do banco, executa a ação e então repete.
SITE_NOT_AVAILABLE — instituição fora do ar
SITE_NOT_AVAILABLE — instituição fora do ar
A instituição está indisponível (correlaciona com
connector/status_updated → OFFLINE).
Resolução: aguardar, monitorar a página de status e tentar mais tarde.USER_NOT_SUPPORTED — perfil não suportado pelo conector
USER_NOT_SUPPORTED — perfil não suportado pelo conector
O conector não suporta este perfil de usuário (ex.: conta empresarial em conector PF).
Resolução: usar o conector correto.
CONNECTOR_DISABLED — conector desabilitado pela plataforma
CONNECTOR_DISABLED — conector desabilitado pela plataforma
O conector está temporariamente desabilitado pela plataforma. Resolução: aguardar a
reabilitação; não fazer retry programático.
CONNECTION_ERROR — erro transitório de rede/instituição
CONNECTION_ERROR — erro transitório de rede/instituição
Erro genérico transitório de rede ou da instituição. A Malvo já realiza até 3 tentativas no
total, separadas por 10 segundos, antes de finalizar a execução. Resolução: se ainda
falhar, tente novamente mais tarde; não recrie o Item.
UPDATING → UPDATED e um webhook item/updated é disparado.
Relacionado
- Erros — envelope
GlobalErrorResponse,errors[]de validação e ticket de suporte. - Limites de uso — a resposta 429 e a estratégia de retry.
- Limites do Open Finance — o aviso
423e oPARTIAL_SUCCESS.