# Erros

Identifique falhas de autenticação, validação, permissão e provedor.

## Formato

Erros de validação usam `error: "Validation failed"` e `details`. O campo `details` do 422 pode variar. Outros erros de domínio podem incluir `code`.

| HTTP | Quando | Exemplo | code |
| --- | --- | --- | --- |
| `401` | Headers de autenticação ausentes. | Missing X-Public-Key / X-Secret-Key | — |
| `401` | Chaves inválidas. | Invalid credentials | — |
| `403` | Empresa inativa. | Enterprise inactive | — |
| `403` | KYC da empresa ainda não aprovado. | KYC approval required | — |
| `403` | Método de pagamento não habilitado para a empresa. | Payment method 'pix' is not enabled for this enterprise | PERMISSION_DENIED |
| `404` | Rota HTTP inexistente no gateway. | Not found | — |
| `422` | Payload inválido. | Validation failed | — |
| `422` | Sem rota de provedor ativa para a operação. | No active provider route for operation: pix_cash_in | ROUTE_NOT_FOUND |
| `422` | amount não é um inteiro positivo. | Amount for pix must be greater than zero, received 0 | INVALID_AMOUNT |
| `422` | amount abaixo do ticket mínimo configurado para a empresa ou o gateway. | Amount is below pix minimum ticket of 100 centavos | TICKET_MINIMUM_NOT_MET |
| `422` | amount acima do ticket máximo configurado. | Amount exceeds pix ticket limit of 1000000 centavos | TICKET_LIMIT_EXCEEDED |
| `500` | Falha inesperada no gateway. | Internal server error | — |
| `502` | Falha retornada pelo provedor. | Provider Medusa: upstream timeout | PROVIDER_ERROR |

## 422

```json title="validation.json"
{
  "error": "Validation failed",
  "details": "Expected property 'paymentMethod' to be equal to 'pix'"
}
```

```json title="route.json"
{
  "error": "No active provider route for operation: pix_cash_in",
  "code": "ROUTE_NOT_FOUND"
}
```

## 502

```json title="provider.json"
{
  "error": "Provider Medusa: upstream timeout",
  "code": "PROVIDER_ERROR"
}
```

## Como tratar

- 401/403: corrija chaves, ativação e KYC.
- 422: ajuste o body.
- 502: trate como falha de provedor.