Central de Erros & Status

Formato do Corpo de Erro

Toda resposta de erro da API segue este formato:

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

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.

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 — 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`.

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.

Primeiros Passos

Endpoints API

Infraestrutura

Referência

Central de Erros & Status

Formato do Corpo de Erro

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

Status das Cobranças PIX (Inbound)

Status de Saques PIX (Outbound)

Tabela de Eventos de Webhook

​Formato do Corpo de Erro

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

​Status das Cobranças PIX (Inbound)

​Status de Saques PIX (Outbound)

​Tabela de Eventos de Webhook

Formato do Corpo de Erro

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

Status das Cobranças PIX (Inbound)

Status de Saques PIX (Outbound)

Tabela de Eventos de Webhook