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

# Erros e diagnóstico

> Interprete respostas de erro e investigue uma chamada com segurança.

Erros retornam um código estável, uma mensagem em português e o `requestId` da requisição.

```json theme={"system"}
{
  "error": "validation_error",
  "message": "Dados da requisição inválidos.",
  "requestId": "req_...",
  "details": [
    {
      "path": "payer.taxId",
      "message": "CPF ou CNPJ inválido."
    }
  ]
}
```

| HTTP | Código comum | Ação |
| - | - | - |
| 400 | `validation_error` | Corrija campos, tipos ou formato |
| 400 | `invalid_idempotency_key` | Envie uma chave no formato aceito |
| 401 | `invalid_api_key` | Confira ambiente, validade, revogação e IP |
| 403 | `insufficient_scope` | Adicione o escopo necessário a uma nova chave |
| 404 | `payment_not_found` | Confira UUID e organização |
| 409 | `idempotency_conflict` | Não reutilize uma chave para outra operação |
| 422 | `refund_exceeds_payment` | Reduza a devolução ao valor disponível |
| 429 | Limite de requisições | Aplique backoff com jitter |
| 503 | `provider_unavailable` | Verifique a habilitação do provedor |

Ao pedir suporte, informe `requestId`, rota, ambiente e horário. Nunca envie a chave completa.

Falhas internas do provedor de pagamentos usam o código genérico `provider_error` e uma mensagem neutra. Detalhes da integração são mantidos nos registros internos da MingoPay.

`503 refund_unavailable` significa que o provedor da cobrança não oferece devolução pela integração. A solicitação é recusada antes de criar uma devolução ou reservar saldo. A integração atual do provedor de pagamentos não oferece esse recurso; não repita com novas chaves idempotentes.

Organizações suspensas (`restricted`) ou encerradas (`closed`) recebem `403 organization_not_active` em chamadas autenticadas por chave, tanto no sandbox quanto em produção. Uma chave válida não remove a suspensão; corrija a situação da conta antes de tentar novamente.


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