Referência da API
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
validation.json
{
"error": "Validation failed",
"details": "Expected property 'paymentMethod' to be equal to 'pix'"
}route.json
{
"error": "No active provider route for operation: pix_cash_in",
"code": "ROUTE_NOT_FOUND"
}#502
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.
Esta página foi útil?