Erros da API de Charges

A API de Charges devolve erros de três formas:

Erro na requisição: a resposta tem status 4xx ou 5xx e o objeto error. Os erros de validação dos dados enviados recusam a requisição antes de criar a cobrança. Um erro de servidor (5xx) ou um tempo limite excedido pode acontecer depois que a cobrança foi criada: antes de tentar de novo, liste as cobranças filtrando pelo orderId do pedido.
Cobrança recusada: o pagamento foi processado e recusado. A cobrança existe e tem status: failed. Esse é o caso que também chega por webhook.
Reprovação do antifraude: o antifraude reprovou a cobrança, antes ou depois da autorização. O status final depende de quando o antifraude roda e das opções do provedor antifraude. Veja Reprovação do antifraude.

Cobrança recusada

Quando o emissor ou o provedor recusa o pagamento, a cobrança fica com status: failed. A resposta de POST /v1/charges, a consulta em GET /v1/charges/{id} e o evento transaction.failed trazem os mesmos campos:

{
  "id": "64254aef-82f2-48ba-a185-d65343462833",
  "status": "failed",
  "error": {
    "type": "card_declined",
    "declinedCode": "expired_card"
  },
  "transactionRequests": [
    {
      "providerType": "SANDBOX",
      "requestStatus": "failed",
      "requestType": "authorization",
      "providerError": {
        "retryable": false,
        "declinedCode": "expired_card",
        "message": null,
        "networkDeniedReason": "sandbox expired card",
        "networkDeniedMessage": "expired_card"
      }
    }
  ]
}

error.declinedCode é o código padronizado pela Malga. Os valores estão na tabela de declinedCode.
providerError.networkDeniedReason e providerError.networkDeniedMessage trazem o código e a mensagem originais do provedor. Use para investigar um caso, não para regras.

O significado de cada campo está em Erros recebidos por webhook. Uma cobrança failed pode vir sem o objeto error: ele só aparece quando existe um declinedCode. Isso acontece, por exemplo, quando a cobrança falha antes de chegar a um provedor. Use o status para saber se a cobrança foi recusada e trate a ausência de código como recusa genérica.

Reprovação do antifraude

Quando o antifraude reprova uma cobrança, o resultado não aparece em error. A análise fica em uma tentativa com requestType: anti_fraud, no campo transactionRequests[].fraudAnalysis.status, que vale reproved. Essa tentativa tem requestStatus: success, porque a análise foi concluída, e não traz providerError. O status final da cobrança depende de quando o antifraude roda e das opções do provedor antifraude:

Quando o antifraude roda	Status da cobrança após a reprovação
Antes do adquirente (`runBeforeCharge: true`)	`failed`: a cobrança não chega ao adquirente e gera `transaction.failed`, em geral sem o objeto `error`. Com `captureOnReproved: true`, a cobrança segue para o adquirente apesar da reprovação
Depois da pré-autorização	`canceled`, quando a Malga anula a pré-autorização (`refundOnReproved`, ligado por padrão). Se a anulação falhar, `pre_authorized`
Depois da pré-autorização, com captura de reprovadas	Com `captureOnReproved: true` e `refundOnReproved: false`: `authorized`, se a captura funcionar, ou `pre_authorized`, se falhar. Com as duas opções ligadas, a Malga captura e depois anula, e o status final segue o resultado da anulação

Os arranjos de capture e runBeforeCharge estão em Antifraude síncrono.

{
  "id": "64254aef-82f2-48ba-a185-d65343462833",
  "status": "canceled",
  "transactionRequests": [
    {
      "requestStatus": "success",
      "requestType": "anti_fraud",
      "fraudAnalysis": {
        "status": "reproved"
      }
    }
  ]
}

Para detectar a reprovação, leia fraudAnalysis.status, qualquer que seja o status da cobrança. Não dependa do evento transaction.failed nem de error.declinedCode.

Formato do erro na requisição

{
  "error": {
    "type": "card_declined",
    "code": 400,
    "declined_code": "invalid_cvv",
    "message": "Invalid card cvv. Check the data and try again"
  }
}

Campo	Descrição
`type`	Categoria do erro
`code`	Status HTTP da resposta
`declined_code`	Código estável do erro, quando existe. Use para tratar o erro no seu sistema
`message`	Texto do erro. Pode mudar ou ser traduzido: não use em regras
`details`	Lista de textos com detalhes, como os campos inválidos
`context`	Valores do erro em campos, quando existem (por exemplo, `sellerId`)
`retry_after_minutes`	Minutos até a próxima tentativa permitida. Só no `429` do estorno
`retry_after_at`	Data e hora (UTC) da próxima tentativa permitida. Só no `429` do estorno

No erro da requisição o código vem em declined_code (com sublinhado). Na cobrança recusada e no webhook, o código vem em declinedCode. A exceção é o 401 de token expirado, que também usa declinedCode. type e declined_code são texto aberto: trate um valor que você não conhece como erro genérico.

Erros na requisição

Os erros estão agrupados por assunto. Escolha uma aba:

HTTP	`type`	`declined_code`	`message`	Quando acontece
400	`card_declined`	`invalid_number`	Invalid card number. Check the data and try again	Número do cartão inválido
400	`card_declined`	`invalid_card_holder_name`	Invalid holder name. Check the data and try again	Nome do portador inválido
400	`card_declined`	`invalid_expiration_date`	Invalid expiration date. Check the data and try again	Data de validade inválida
400	`card_declined`	`invalid_cvv`	Invalid card cvv. Check the data and try again	CVV inválido
400	`card_declined`	`required_cvv`	The security code (CVV) is required to proceed. Check card details and try again	CVV obrigatório não enviado
400	`card_failed`	-	This card has a failed status and cannot be used to make a payment	Cartão salvo com status `failed`
401	`card_declined`	`expired_token` (em `declinedCode`)	Expired Token	Token de cartão expirado ou inválido
404	`card_pending_token_expired`	-	The card is in pending status: it has not been validated with a CVV yet (…)	Cartão pendente de validação usado sem CVV

HTTP	`type`	`message`	Quando acontece
404	`invalid_request_error`	Card not found	`cardId` inexistente ou de outro cliente
404	`invalid_request_error`	Customer not found	`customerId` inexistente
404	`invalid_request_error`	Token CVV Id Not Found	Token de CVV inexistente
404	`invalid_request_error`	Seller not found	Seller do split inexistente
404	`invalid_request_error`	Session not found	Session inexistente
404	`invalid_request_error`	Transaction not found	Cobrança inexistente na captura, no estorno ou na consulta
400	`not_found`	Merchant not found	`merchantId` inexistente
400	`not_found`	Provider not found	Nenhum provedor configurado para o merchant e o meio de pagamento

HTTP	`type`	`declined_code`	Quando acontece
400	`bad_request`	-	Split misto (`percentage` e `amount` juntos) ou soma do split maior que o valor da cobrança
400	`bad_request`	`split_percentage_sum_cannot_be_greater_than_100`	Soma de `percentage` acima de 100, no `splitRules` ou em um `provider[].splitRules`
400	`bad_request`	-	Seller bloqueado, inválido ou sem cadastro no provedor
422	`unprocessable_entity`	`split_multiple_transaction_owners`	Mais de uma regra com `transactionOwner: true`
422	`unprocessable_entity`	`split_multiple_liable_not_supported`	Mais regras com `liable: true` do que o provedor aceita
422	`unprocessable_entity`	`platform_fee_*` e `split_amount_mismatch`	Recusa pela taxa da plataforma. Os códigos estão em Taxa da plataforma
503	`service_unavailable`	`platform_fee_config_unavailable`	Configuração da taxa da plataforma indisponível. Tente de novo

HTTP	`type`	`declined_code`	Quando acontece
400	`invalid_request_error`	`provider_not_configured_for_3ds2`	Cobrança com 3DS Malga ou autenticação externa sem provedor configurado para `3ds2_malga`
400	`invalid_request_error`	`provider_not_configured_for_required_capabilities`	Nenhum provedor atende ao mesmo tempo `3ds2_malga` e split

Os erros da autenticação 3DS estão em Principais erros do 3DS Malga.

HTTP	`type`	`message`	Quando acontece
400	`invalid_request_error`	Amount cannot be greater than the transaction amount	Valor da captura maior que o da cobrança
409	`invalid_request_error`	Transaction has not pre-authorized	Captura de cobrança que não está pré-autorizada
409	`invalid_request_error`	Transaction is not pending	Autorização 3DS de uma cobrança que não está pendente
409	`invalid_request_error`	Charge already voided/canceled	Cobrança já cancelada ou estornada
409	`invalid_request_error`	It is not possible to make a refund greater than the payment amount	Estorno acima do valor pago
409	`conflict`	Transaction is processing	Outra operação na mesma cobrança, ou a mesma chave de idempotência, ainda está em processamento
422	`unprocessable_entity`	Transaction failed	Cancelamento ou estorno de cobrança fora de `authorized`, `pre_authorized` ou `pending`
429	`too_many_requests`	Too many consecutive refund failures for this charge. Please wait before trying again.	Estorno recusado por falhas seguidas no provedor. Aguarde até `retry_after_at`
422	`unprocessable_entity`	This charge has too many refund failures at the provider. (…)	Estorno bloqueado. Acione o suporte da Malga

Veja como funciona o limite de falhas no estorno.

HTTP	`type`	Quando acontece
400	`bad_request`	Campo obrigatório ausente ou em formato inválido. `details` lista os problemas
403	`forbidden`	Cliente sem permissão para usar o 3D Secure
500	`api_error`	Erro inesperado (`message: "Unexpected error"`). Entre em contato com o suporte
504	`gateway_timeout`	Tempo limite excedido. Consulte a cobrança antes de tentar de novo

Exemplos de resposta

400 · CVV inválido

{
  "error": {
    "type": "card_declined",
    "code": 400,
    "declined_code": "invalid_cvv",
    "message": "Invalid card cvv. Check the data and try again"
  }
}

400 · CVV obrigatório

{
  "error": {
    "type": "card_declined",
    "code": 400,
    "declined_code": "required_cvv",
    "message": "The security code (CVV) is required to proceed. Check card details and try again"
  }
}

401 · Token expirado

{
  "error": {
    "type": "card_declined",
    "code": 401,
    "message": "Expired Token",
    "declinedCode": "expired_token"
  }
}

404 · Cartão não encontrado

{
  "error": {
    "type": "invalid_request_error",
    "code": 404,
    "message": "Card not found"
  }
}

400 · Soma de percentuais do split acima de 100

{
  "error": {
    "type": "bad_request",
    "code": 400,
    "declined_code": "split_percentage_sum_cannot_be_greater_than_100",
    "message": "Split percentage sum cannot be greater than 100"
  }
}

422 · Mais de um dono da venda no split

{
  "error": {
    "type": "unprocessable_entity",
    "code": 422,
    "declined_code": "split_multiple_transaction_owners",
    "message": "Only one split rule can have transactionOwner true."
  }
}

400 · Provedor sem 3DS Malga

{
  "error": {
    "type": "invalid_request_error",
    "code": 400,
    "declined_code": "provider_not_configured_for_3ds2",
    "message": "No provider configured for Malga 3DS2 or external authentication charge",
    "details": ["no provider configured with paymentTypes=3ds2_malga for this charge"]
  }
}

409 · Operação em processamento

{
  "error": {
    "type": "conflict",
    "code": 409,
    "message": "Transaction is processing"
  }
}

409 · Captura de cobrança não pré-autorizada

{
  "error": {
    "type": "invalid_request_error",
    "code": 409,
    "message": "Transaction has not pre-authorized"
  }
}

429 · Estorno com falhas seguidas

{
  "error": {
    "type": "too_many_requests",
    "code": 429,
    "message": "Too many consecutive refund failures for this charge. Please wait before trying again.",
    "retry_after_minutes": 30,
    "retry_after_at": "2026-11-03T14:30:00.000Z"
  }
}

500 · Erro inesperado

{
  "error": {
    "type": "api_error",
    "code": 500,
    "message": "Unexpected error"
  }
}

Comece na Malga

Conexões

Guias

Serviços adicionais

Erros da API de Charges

Cobrança recusada

Reprovação do antifraude

Formato do erro na requisição

Erros na requisição

Exemplos de resposta

​Cobrança recusada

​Reprovação do antifraude

​Formato do erro na requisição

​Erros na requisição

​Exemplos de resposta

Cobrança recusada

Reprovação do antifraude

Formato do erro na requisição

Erros na requisição

Exemplos de resposta