Pular para o conteúdo principal

Erros

Quando uma requisição falha, a API retorna um status HTTP de erro e uma resposta estruturada com um ou mais erros em data.errors.

Resposta de erro​

{
"status": "error",
"data": {
"errors": [
{
"errorMessage": "resourceNotFound",
"errorType": "GENERAL",
"errorId": "3f69d9b6",
"errorDescription": "Resource not found",
"errorField": null,
"params": [],
"requestParams": {}
}
]
}
}
CampoDescrição
errorMessageCódigo de erro legível por máquina. Use-o no tratamento de erros.
errorTypeCategoria do erro: FIELD (um campo é inválido, veja errorField), FORM (a requisição como um todo) ou GENERAL.
errorIdIdentificador deste erro. Registre-o e inclua-o nos contatos com o suporte.
errorDescriptionDescrição legível para pessoas. Não a use na lógica do programa: o texto pode mudar.
errorFieldO campo da requisição relacionado ao erro, se houver.
paramsParâmetros adicionais do erro, se houver.
requestParamsParâmetros da requisição relacionados ao erro, se houver.

Códigos de erro comuns​

A lista abaixo traz os códigos que uma integração costuma precisar tratar. Ela não é completa: um método pode retornar outros códigos. Trate um errorMessage desconhecido como erro geral e registre o errorId dele.

errorMessageO que significa
missingRequestParameterFalta um parâmetro obrigatório.
methodArgumentTypeMismatchUm parâmetro tem o tipo errado, por exemplo texto em vez de número.
httpMessageNotReadableO corpo da requisição não é um JSON válido ou não corresponde à estrutura esperada.
unrecognizedFieldO corpo da requisição contém um campo que o método não aceita.
badParametersExceptionUm ou mais parâmetros são inválidos.
badFormatAmountExceptionO valor tem um formato inválido.
notEnoughMoneyExceptionA carteira de origem não tem fundos suficientes.
limitPerTransactionExceptionO valor excede o limite por transação.
limitPerMonthExceptionA transação excede o limite mensal.
walletDoesNotExistA carteira da requisição não existe.
walletCurrencyIncorrectExceptionA moeda da carteira não corresponde à requisição.
recipientDoesNotExistExceptionA conta do destinatário não existe.
paymentMethodNotAvailableForMerchantApiO método de pagamento não está disponível para a sua API.
resourceNotFoundO endpoint não existe.
attemptsHaveEndedExceptionA conta esgotou o limite de requisições por hora. Veja Limite de requisições.
tryAgainAfterAWhileOs dados estão temporariamente bloqueados. Tente novamente mais tarde.
serviceTemporaryUnavailableUm serviço está temporariamente indisponível. Tente novamente mais tarde.
internalServerErrorErro inesperado do servidor.

Códigos de status HTTP​

StatusSignificado
400A requisição está malformada, contém parâmetros inválidos ou não pode ser processada. Também é retornado quando um pedido ou outra entidade não é encontrado.
401Os cabeçalhos de autenticação estão ausentes ou são inválidos, ou a conta esgotou o limite de requisições por hora (attemptsHaveEndedException).
404O endpoint solicitado não foi encontrado.
405O endpoint não aceita este método HTTP (httpMethodNotAllowed).
409Os dados estão temporariamente bloqueados (tryAgainAfterAWhile).
415O Content-Type da requisição não é suportado (unknownContentType).
500Erro inesperado do servidor (internalServerError).
503Um serviço está temporariamente indisponível (serviceTemporaryUnavailable).

Não deduza o código de erro só pelo status HTTP: o mesmo status pode vir com valores diferentes de errorMessage.

Tratar erros​

  • Registre o errorId de cada erro.
  • Verifique errorField para encontrar o campo a corrigir.
  • Após um 401, verifique o nome da API, o e-mail da conta, o token e o horário UTC do servidor.
  • Se a API não tiver permissão para a operação ou o seu servidor não puder chamá-la, verifique as permissões da API e a lista de IPs permitidos na seção de ferramentas de pagamento.

Repetir com segurança​

Os erros se dividem em dois grupos:

  • Temporários — 409 (tryAgainAfterAWhile), 503 (serviceTemporaryUnavailable) e timeouts. Repita requisições de leitura e de validação com um intervalo cada vez maior entre as tentativas. Para requisições que criam uma transação ou uma fatura, veja abaixo.
  • Permanentes — erros de autenticação e de parâmetros. Corrija a requisição em vez de repeti-la.

Requisições de validação (/api/withdrawal/validation/…) e consultas não criam nada e podem ser repetidas.

A Merchant API não tem chave de idempotência. Uma requisição que cria uma transação ou uma fatura pode dar timeout ou falhar depois que a API já a processou, e repeti-la pode criar uma segunda. Após um timeout ou um erro 5xx, verifique se ela foi criada antes de repetir:

  • Para pagamentos, verifique o histórico de transações e o saldo da carteira. Veja Consulta do histórico de transações. Cada requisição de pagamento que passa na validação cria uma nova transação, mesmo que repita uma anterior.
  • Para faturas, consulte o pedido pelo seu orderId. Veja Consulta de pedido de pagamento. Se você enviar sciName, a Volet.com rejeita uma segunda fatura com o mesmo orderId para esse Hosted Checkout.

Se ainda não estiver claro se um pagamento foi criado, fale com o suporte antes de enviá-lo novamente.

  • Introdução — URL base, autenticação e formato das requisições
  • Status — status de transações e de pagamentos