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

# Central de Erros & Status

> Mapeamento exaustivo de todos os códigos de resposta HTTP, status de cobranças, status de saques e eventos do sistema.

## Formato do Corpo de Erro

Toda resposta de erro da API segue este formato:

```json theme={null}
{
  "statusCode": 400,
  "message": "Descrição legível do que deu errado",
  "error": "Request Error",
  "timestamp": "2026-08-26T12:00:00.000Z",
  "path": "/v1/charges"
}
```

<Note>
  O campo `error` retorna o texto genérico `"Request Error"` na maioria dos casos — **não** use esse campo para diferenciar tipos de erro programaticamente. Use o `statusCode` combinado com o conteúdo de `message`. A API não retorna um campo `code` estruturado (ex: `VALIDATION_ERROR`); a tabela abaixo é apenas descritiva, para facilitar a leitura humana das causas mais comuns por status HTTP.
</Note>

## Manual Exaustivo de Erros HTTP (4xx & 5xx)

| HTTP Status             | Causa Comum                                                                                                      | Como Resolver                                                                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`       | Parâmetro inválido (ex: CPF/CNPJ com dígitos errados, ou `amount` enviado como número em vez de string decimal). | Envie `amount` como string com duas casas decimais (ex: `"49.00"`) — veja [Formato de Valores](/parametros) — e valide o CPF com 11 dígitos. |
| `401 Unauthorized`      | Chave de API ausente, revogada ou malformatada.                                                                  | Verifique o header `Authorization: Bearer sk_live_...`.                                                                                      |
| `402 Payment Required`  | Tentativa de saque maior que o saldo disponível na conta.                                                        | Consulte o saldo via `GET /v1/balance` antes de transferir.                                                                                  |
| `403 Forbidden`         | A chave de API não possui o escopo necessário para a rota chamada.                                               | Crie uma chave com os escopos adequados (`payments:write`, etc.) no Dashboard.                                                               |
| `404 Not Found`         | Cobrança, saque ou cliente pesquisado não existe.                                                                | Certifique-se de utilizar o ID válido retornado na criação.                                                                                  |
| `429 Too Many Requests` | Limite de requisições por minuto foi ultrapassado.                                                               | Aguarde o tempo indicado no cabeçalho `Retry-After` antes de tentar novamente.                                                               |
| `500 Server Error`      | Instabilidade momentânea no banco central ou adquirente.                                                         | A API da KavroPay realiza failover automático alternando adquirentes em tempo real.                                                          |

## Status das Cobranças PIX (Inbound)

| Status (`status`) | Nome Exibido         | Significado & Comportamento                                                                                         |
| ----------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `waiting_payment` | Aguardando Pagamento | Cobrança gerada com sucesso e QR Code ativo aguardando leitura pelo pagador.                                        |
| `paid`            | Pago / Confirmado    | Pagamento PIX efetuado e liquidado no mesmo instante. Saldo liberado na sua conta.                                  |
| `expired`         | Expirado             | O tempo de validade (ex: 30 min) foi atingido sem que o cliente tenha realizado o pagamento.                        |
| `cancelled`       | Cancelado            | Cobrança cancelada manualmente pelo lojista via [`POST /v1/charges/{id}/cancel`](/cobrancas-pix#cancelar-cobranca). |

## Status de Saques PIX (Outbound)

| Status (`status`)        | Nome Exibido       | Significado & Comportamento                                                         |
| ------------------------ | ------------------ | ----------------------------------------------------------------------------------- |
| `pending`                | Em Fila            | Solicitação de saque registrada e aguardando processamento.                         |
| `processing`             | Em Processamento   | Saque enviado para a rede do Banco Central.                                         |
| `paid_out` / `completed` | Concluído          | Transferência PIX liquidada com sucesso na conta de destino.                        |
| `failed`                 | Falhou / Estornado | Falha no envio (ex: chave inexistente). Valor e taxas são estornados integralmente. |

## Tabela de Eventos de Webhook

| Evento (`event`)       | Descrição         | Quando é Disparado?                                                     |
| ---------------------- | ----------------- | ----------------------------------------------------------------------- |
| `charge.paid`          | Cobrança Paga     | Disparado no exato instante em que o pagamento do cliente é confirmado. |
| `charge.expired`       | Cobrança Expirada | Disparado quando o tempo de expiração vence sem pagamento.              |
| `withdrawal.completed` | Saque Concluído   | Disparado quando a transferência PIX de saída é entregue.               |
| `withdrawal.failed`    | Saque Rejeitado   | Disparado se a transferência falhar e o saldo for estornado.            |