> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Responda em português brasileiro, na segunda pessoa ("você"), com base na documentação Malga.
> Não invente endpoints, parâmetros, status codes ou comportamentos de API. Se não estiver na docs, diga que não encontrou e indique a página mais próxima.
> Use os headers X-Client-Id e X-Api-Key nos exemplos de autenticação.
> Motor de Assinaturas refere-se a /v1/subscriptions* (cycles, trial, retentativas, webhooks subscription.*). Não chame de "motor de recorrência".
> Recorrência (provedor) é paymentMethod.recurrence em POST /v1/charges (initial / subsequent / unscheduled), distinto do Motor de Assinaturas.
> Sandbox é ambiente de testes e não afeta produção.

# Erros da API de Charges

> Consulte os erros da API de Charges da Malga: formato do objeto error, recusas do emissor e do provedor, códigos de validação de cartão, split, 3DS, captura e estorno, com exemplos de resposta.

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](https://docs.malga.io/api-reference/charges/listar-cobrancas.md) 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](https://docs.malga.io/documentations/welcome/errors-webhooks.md).
* **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](#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`](https://docs.malga.io/api-reference/charges/realizar-nova-cobranca), a consulta em [`GET /v1/charges/{id}`](https://docs.malga.io/api-reference/charges/recuperar-detalhes-de-cobranca) e o evento `transaction.failed` trazem os mesmos campos:

```json theme={null}
{
  "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](https://docs.malga.io/documentations/type-tables/declined-code.md).
* `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](https://docs.malga.io/documentations/welcome/errors-webhooks.md).

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](https://docs.malga.io/documentations/anti-fraud/intro.md) 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](https://docs.malga.io/documentations/anti-fraud/sync-anti-fraud.md).

```json theme={null}
{
  "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

```json theme={null}
{
  "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 |

> [!WARNING]
>
> 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:

> [tab] Cartão
>
> | 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 |

> [tab] Não encontrado
>
> | 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 |

> [tab] Split e taxa
>
> | 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](https://docs.malga.io/documentations/split/platform-fee.md) |
> | 503 | `service_unavailable` | `platform_fee_config_unavailable` | Configuração da taxa da plataforma indisponível. Tente de novo |

> [tab] 3DS
>
> | 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](https://docs.malga.io/documentations/3ds2-malga/3ds-malga/principais-erros.md).

> [tab] Captura e estorno
>
> | 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](https://docs.malga.io/documentations/more/limite-falhas-estorno.md).

> [tab] Validação e infra
>
> | 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

> [accordion] 400 · CVV inválido
>
> ```json theme={null}
> {
>   "error": {
>     "type": "card_declined",
>     "code": 400,
>     "declined_code": "invalid_cvv",
>     "message": "Invalid card cvv. Check the data and try again"
>   }
> }
> ```

> [accordion] 400 · CVV obrigatório
>
> ```json theme={null}
> {
>   "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"
>   }
> }
> ```

> [accordion] 401 · Token expirado
>
> ```json theme={null}
> {
>   "error": {
>     "type": "card_declined",
>     "code": 401,
>     "message": "Expired Token",
>     "declinedCode": "expired_token"
>   }
> }
> ```

> [accordion] 404 · Cartão não encontrado
>
> ```json theme={null}
> {
>   "error": {
>     "type": "invalid_request_error",
>     "code": 404,
>     "message": "Card not found"
>   }
> }
> ```

> [accordion] 400 · Soma de percentuais do split acima de 100
>
> ```json theme={null}
> {
>   "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"
>   }
> }
> ```

> [accordion] 422 · Mais de um dono da venda no split
>
> ```json theme={null}
> {
>   "error": {
>     "type": "unprocessable_entity",
>     "code": 422,
>     "declined_code": "split_multiple_transaction_owners",
>     "message": "Only one split rule can have transactionOwner true."
>   }
> }
> ```

> [accordion] 400 · Provedor sem 3DS Malga
>
> ```json theme={null}
> {
>   "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"]
>   }
> }
> ```

> [accordion] 409 · Operação em processamento
>
> ```json theme={null}
> {
>   "error": {
>     "type": "conflict",
>     "code": 409,
>     "message": "Transaction is processing"
>   }
> }
> ```

> [accordion] 409 · Captura de cobrança não pré-autorizada
>
> ```json theme={null}
> {
>   "error": {
>     "type": "invalid_request_error",
>     "code": 409,
>     "message": "Transaction has not pre-authorized"
>   }
> }
> ```

> [accordion] 429 · Estorno com falhas seguidas
>
> ```json theme={null}
> {
>   "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"
>   }
> }
> ```

> [accordion] 500 · Erro inesperado
>
> ```json theme={null}
> {
>   "error": {
>     "type": "api_error",
>     "code": 500,
>     "message": "Unexpected error"
>   }
> }
> ```


## Related topics

- [Tratamento de erros na integração](https://docs.malga.io/documentations/welcome/errors.md)
- [Erros recebidos por webhook](https://docs.malga.io/documentations/welcome/errors-webhooks.md)
- [Tabela de DeclinedCode da Malga](https://docs.malga.io/documentations/type-tables/declined-code.md)
- [Realizar nova cobrança](https://docs.malga.io/api-reference/charges/realizar-nova-cobranca.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.