Erros e Códigos de Status

Como interpretar e tratar respostas de erro da API

Formato padrão de erro

Quando uma requisição falha por validação, autenticação ou erro de negócio, a API responde com um corpo JSON no seguinte formato:

{
  "success": false,
  "message": "Descrição legível do erro"
}

Sempre trate a resposta programaticamente pelo código de status HTTP retornado, conforme a semântica definida na RFC 9110 (HTTP Semantics) — o campo message é destinado a leitura humana/logging e seu texto pode mudar entre versões da API. Alguns endpoints (como o de saque bloqueado) retornam campos adicionais específicos do contexto; consulte a referência Swagger para o schema exato de cada resposta.

Códigos de status HTTP

Código Significado Como tratar
200 Sucesso. Para a maioria dos endpoints, retorna JSON com os dados da operação; alguns endpoints também podem retornar a imagem do QR Code diretamente (image/png). Processe o corpo normalmente. Para webhooks recebidos, responder 200 (ou qualquer 2xx) confirma o recebimento e evita reenvio.
401 Não autorizado. Nos endpoints de pagamento/saque, indica código de integração ausente ou inválido. Nos endpoints de webhook, indica cabeçalho Authorization ausente ou com token incorreto. Não repita a requisição sem corrigir a credencial. Confirme o valor do code (ou do token Basic Auth) na origem — veja a página de Autenticação.
403 Proibido por regra de negócio. Um exemplo real da API é o bloqueio de saques quando há taxas pendentes acima de um determinado limite — nesse caso, o corpo da resposta detalha o valor pendente que precisa ser quitado para desbloquear a operação. Não é um erro de autenticação nem de validação de campos — trate como uma condição de negócio que exige uma ação (ex.: pagar uma taxa pendente) antes de tentar novamente.
422 Erro de validação. Parâmetros obrigatórios ausentes, em formato incorreto, ou combinações inválidas (por exemplo, enviar dois parâmetros mutuamente exclusivos ao mesmo tempo). Leia o campo message para identificar qual validação falhou e corrija o payload antes de reenviar. Não adianta repetir a mesma requisição sem alterá-la.
429 Limite de requisições excedido (rate limiting). A resposta inclui a mensagem "Too Many Attempts.". Implemente backoff exponencial antes de tentar novamente. Veja a seção de rate limiting abaixo para os limites por endpoint.
500 Erro interno do servidor. Não é causado por dados inválidos enviados por você. Trate como transitório: aguarde um curto intervalo e tente novamente. Se o erro persistir, registre o horário e o identificador da transação (se houver) e acione o suporte técnico.

Rate limiting

A maioria dos endpoints da API tem limite de 60 requisições por minuto por IP. Os endpoints de webhook (/webhooks/*) têm um limite mais alto, de 100 requisições por minuto, já que recebem chamadas de sistemas automatizados do provedor de pagamento.

Ao ultrapassar o limite, a API responde 429 com {"message": "Too Many Attempts."}. Evite fazer polling agressivo de status de transação — prefira configurar um webhook para ser notificado do evento, reservando o polling apenas como verificação de contingência.

Boas práticas gerais de tratamento

  • Trate erros 4xx (erro do cliente) e 5xx (erro do servidor) de forma diferente: 4xx normalmente exige correção da requisição antes de reenviar; 5xx pode ser tentado novamente após um intervalo.
  • Sempre registre (log) o código de status, o corpo da resposta e, quando disponível, o identificador da transação — isso acelera o diagnóstico em caso de suporte.
  • Para chamadas recebidas no seu endpoint de webhook, valide a autenticação antes de processar qualquer coisa, e trate eventos duplicados de forma idempotente (verificando se aquele identificador de transação já foi processado).
  • Nunca assuma sucesso silenciosamente: só considere uma cobrança confirmada após ver o status correspondente na resposta da API ou no payload do webhook.

Ao usar o parâmetro de carteira personalizada (endereço Liquid customizado) disponível em alguns endpoints, lembre-se que transações na Liquid Network não podem ser revertidas. Erros de validação relacionados a esse campo devem ser tratados com atenção redobrada antes de reenviar a requisição.

Próximos passos

Consulte a referência Swagger para ver os schemas completos de erro por endpoint, ou o FAQ Técnico para dúvidas sobre versionamento e suporte.