> ## 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.

# Limite de falhas no estorno

> Entenda por que a Malga recusa um estorno com os erros 429 ou 422 depois de falhas repetidas no provedor e o que fazer em cada caso.

Quando o provedor recusa várias vezes o estorno de uma mesma cobrança, a Malga para de enviar novos pedidos de estorno ao provedor. Assim, tentativas que tendem a falhar do mesmo jeito não sobrecarregam o provedor.

O limite vale para os estornos feitos pela [requisição de void](/api-reference/charges/estornar-cobranca-aprovada), em qualquer meio de pagamento.

## Como a contagem funciona

* Contam as tentativas de estorno da cobrança no mesmo provedor que não terminaram com sucesso, inclusive as que ainda estão em processamento.
* Um estorno concluído com sucesso zera a contagem.

## Erros retornados

Ao atingir o limite, a requisição de `void` é recusada com um dos erros abaixo:

| HTTP code | `error.type` | Quando acontece | O que fazer |
| - | - | - | - |
| *429* | *too\_many\_requests* | O estorno falhou várias vezes seguidas. O tempo de espera aumenta conforme as falhas se acumulam. | Aguarde até o horário informado em `retry_after_at` e tente de novo. |
| *422* | *unprocessable\_entity* | A cobrança atingiu o limite total de falhas de estorno. O bloqueio é definitivo: esperar não libera um novo estorno. | Não repita a requisição. Se necessário, entre em contato com o suporte da Malga. |

Nesses dois casos, a Malga não envia o pedido ao provedor, não cria um novo `transactionRequest` e não altera o status da cobrança. A resposta é um erro HTTP, e não um `201` com um `transactionRequest` com status `failed`.

### Exemplo de requisição

```bash theme={null}
curl --location --request POST 'https://api.malga.io/v1/charges/YOUR_CHARGE_ID/void' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "amount": 150
  }'
```

### Resposta `429`

O corpo traz o tempo de espera em minutos (`retry_after_minutes`) e o horário em UTC a partir do qual você pode tentar de novo (`retry_after_at`):

```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": 15,
    "retry_after_at": "2026-09-30T14:35:00.000Z"
  }
}
```

### Resposta `422`

```json theme={null}
{
  "error": {
    "type": "unprocessable_entity",
    "code": 422,
    "message": "This charge has too many refund failures at the provider. Please contact Malga support to have the refund processed manually."
  }
}
```

## Como tratar na sua integração

<Steps>
  <Step title="Respeite o tempo de espera do 429">
    Se a sua integração repete o estorno automaticamente, não faça uma nova tentativa antes do horário de `retry_after_at`.
  </Step>

  <Step title="Trate o 422 como erro final">
    Não repita a requisição: a resposta continua sendo `422`, mesmo depois de algum tempo.
  </Step>

  <Step title="Se necessário, fale com o suporte">
    Se precisar de ajuda, entre em contato com o suporte da Malga.
  </Step>
</Steps>

Veja também a [tabela de erros da API](/documentations/welcome/errors).


## Related topics

- [Tratamento de erros na integração](/documentations/welcome/errors.md)
- [Cartão de crédito](/documentations/payment-methods/credit-card.md)
- [Gestão de Cobranças](/documentations/dashboard/charge-details.md)
- [Webhooks v1.1](/documentations/webhooks/webhook1-1.md)