Erros

Toda resposta não-2xx da API da Malvo usa o mesmo envelope de erro, o GlobalErrorResponse. Seus clientes devem ramificar pelo codeDescription (estável), nunca pelo texto de message.

O envelope `GlobalErrorResponse`

{
  "code": 429,
  "message": "Too many requests. Please try again later (see Retry-After header in seconds)",
  "codeDescription": "TOO_MANY_REQUESTS",
  "data": {}
}

Campo	Tipo	Presença	Notas
`code`	number	sempre	Espelha o status HTTP
`message`	string	sempre	Mensagem legível. Não é estável — nunca faça parse
`codeDescription`	string	opcional	Discriminador estável em `SCREAMING_SNAKE_CASE`. Ramifique por ele
`data`	object	opcional	Contexto adicional, livre

Status HTTP

Código	Significado	Causa comum
`200`	OK	Sucesso
`204`	No Content	DELETE bem-sucedido
`400`	Bad Request	Corpo malformado, campo obrigatório ausente ou validação reprovada
`401`	Unauthorized	`X-API-KEY` inválido ou expirado (TTL de ~2h) nos endpoints de dados; chaves de cliente erradas no `POST /auth`
`403`	Forbidden	Sem permissão para o recurso; `X-API-KEY` ausente/expirado no `POST /connect_token`; connect token tentando ler dados de produto
`404`	Not Found	Caminho errado ou id de recurso desconhecido (incl. Items deletados)
`405`	Method Not Allowed	Verbo errado (ex.: GET em endpoint POST)
`406`	Not Acceptable	Pediu um content type que não é JSON
`409`	Conflict	Conflito de estado (ex.: Item já atualizando, update sob throttle)
`429`	Too Many Requests	Limite por IP por minuto excedido
`500`	Internal Server Error	Falha no servidor — repita com backoff
`503`	Service Unavailable	Janela de manutenção

`codeDescription` conhecidos

Brancheie por estes valores estáveis do contrato público.

`codeDescription`	HTTP	Onde aparece	O que fazer
`CLIENT_KEYS_UNAUTHORIZED`	401	`POST /auth`	`clientId`/`clientSecret` errados — confira as credenciais no Dashboard
`CLIENT_DISABLED`	401	`POST /auth`	Credenciais certas, mas a Application está desativada. Repetir não resolve — verifique o Dashboard ou contate o suporte
`ITEM_NOT_FOUND`	404	`POST /connect_token`, `GET/PATCH/DELETE /items/{id}`	`itemId` inexistente ou deletado — verifique o id
`ITEM_IS_ALREADY_UPDATING`	409	`PATCH /items/{id}`, `POST /items/{id}/refresh`	Já há um update em andamento — aguarde terminar
`ITEM_CREATION_LIMIT_EXCEEDED`	409	`POST /items`, `PATCH /items/{id}`	Frequência mínima entre updates não respeitada — não martele o endpoint; use auto-sync
`CLIENT_HAS_ITEM_UPDATES_DISABLED`	409	`PATCH /items/{id}`	Updates manuais desativados para o cliente
`ITEM_ORIGINAL_CONNECTED_WITH_DIFFERENT_ACCOUNT`	400	`PATCH /items/{id}`	O usuário deve reconectar com a conta original
`TOO_MANY_REQUESTS`	429	Qualquer endpoint com limite	Aguarde `RateLimit-Reset` e repita — veja Limites de uso
`INTERNAL_SERVER_ERROR`	500	Qualquer lugar	Repita com backoff exponencial

Erros de validação (`errors[]`)

As falhas de validação de parâmetros em POST /items e PATCH /items/{id} retornam 400 com um array errors[] além dos campos padrão do envelope:

{
  "code": 400,
  "message": "Invalid parameters",
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "message": "cpf must match pattern ^\\d{11}$",
      "parameter": "cpf"
    }
  ]
}

Campo de cada entrada	Tipo	Notas
`code`	string	Classificação do erro
`message`	string	O que falhou
`parameter`	string	O campo que causou a falha

Mapeie cada parameter ao campo do formulário e mostre message ao usuário.

Rastreamento: `x-request-id` / `requestId`

Toda resposta da API carrega um identificador de requisição — no header x-request-id e no campo requestId do corpo. Guarde-o em logs: é o que o suporte usa para localizar a requisição exata.

Códigos de erro de Item (conexão)

Erros de conexão chegam pelo campo error.code do Item (GET /items/{id}) e pelo webhook item/error. Veja como resolver cada um:

INVALID_CREDENTIALS

Usuário digitou usuário/senha errados. Envie-o pelo widget em modo de atualização com o mesmo itemId para reinserir as credenciais.

INVALID_CREDENTIALS_MFA

Token MFA errado ou expirado. Reinicie o fluxo de MFA no modo de atualização.

ALREADY_LOGGED_IN

Sessão do provedor presa em outro dispositivo. Peça ao usuário para sair das outras sessões e tente de novo.

ACCOUNT_LOCKED

Conta bloqueada na instituição após muitas tentativas. Exige intervenção manual do usuário no app do banco; não é recuperável via API.

ACCOUNT_NEEDS_ACTION

A instituição pede que o usuário aceite termos ou atualize o perfil. Ele faz isso no app do banco e então você reexecuta o Item.

SITE_NOT_AVAILABLE

Provedor fora do ar (correlaciona com connector/status_updated → OFFLINE). Aguarde, acompanhe a página de status e tente mais tarde.

USER_AUTHORIZATION_PENDING

Fluxo de consentimento do Open Finance não concluído (ou consentimento revogado). Reemita o consentimento via widget em modo de atualização; se expirou, é preciso um novo consentimento. Veja Consentimentos.

USER_NOT_SUPPORTED

O conector não suporta esse perfil de usuário (ex.: conta PJ num conector PF). Use o conector correto.

CONNECTOR_DISABLED

Conector temporariamente desativado pela plataforma. Aguarde a reativação; não tente programaticamente.

CONNECTION_ERROR

Erro transitório genérico de rede/provedor. Repita com backoff exponencial.

Após a recuperação, o Item flui UPDATING → UPDATED e dispara um webhook item/updated.

Abrir um ticket de suporte

Inclua o máximo possível. O itemId é obrigatório para qualquer problema de conexão — sem ele o suporte não consegue analisar.

itemId (obrigatório)

O identificador do Item afetado.

requestId

Do header x-request-id ou do campo requestId do corpo da resposta com falha.

Timestamp

Data/hora da tentativa que falhou, em ISO 8601 com fuso.

Código e mensagem do erro

De item.error, do onError do widget, do corpo JSON da API ou do payload do webhook.

Status HTTP e corpo

Para falhas de API: o status e o corpo completo da resposta.

connectorId e passos para reproduzir

O connectorId quando for específico de instituição, mais os passos e a frequência (sempre vs. intermitente).

A lista completa de códigos está em Códigos de erro.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

O envelope `GlobalErrorResponse`

Status HTTP

`codeDescription` conhecidos

Erros de validação (`errors[]`)

Rastreamento: `x-request-id` / `requestId`

Códigos de erro de Item (conexão)

Abrir um ticket de suporte

​O envelope GlobalErrorResponse

​Status HTTP

​codeDescription conhecidos

​Erros de validação (errors[])

​Rastreamento: x-request-id / requestId

​Códigos de erro de Item (conexão)

​Abrir um ticket de suporte

O envelope `GlobalErrorResponse`

Status HTTP

`codeDescription` conhecidos

Erros de validação (`errors[]`)

Rastreamento: `x-request-id` / `requestId`

Códigos de erro de Item (conexão)

Abrir um ticket de suporte