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": {}
}
]
}
}
| Campo | Descrição |
|---|---|
errorMessage | Código de erro legível por máquina. Use-o no tratamento de erros. |
errorType | Categoria do erro: FIELD (um campo é inválido, veja errorField), FORM (a requisição como um todo) ou GENERAL. |
errorId | Identificador deste erro. Registre-o e inclua-o nos contatos com o suporte. |
errorDescription | Descrição legível para pessoas. Não a use na lógica do programa: o texto pode mudar. |
errorField | O campo da requisição relacionado ao erro, se houver. |
params | Parâmetros adicionais do erro, se houver. |
requestParams | Parâ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.
errorMessage | O que significa |
|---|---|
missingRequestParameter | Falta um parâmetro obrigatório. |
methodArgumentTypeMismatch | Um parâmetro tem o tipo errado, por exemplo texto em vez de número. |
httpMessageNotReadable | O corpo da requisição não é um JSON válido ou não corresponde à estrutura esperada. |
unrecognizedField | O corpo da requisição contém um campo que o método não aceita. |
badParametersException | Um ou mais parâmetros são inválidos. |
badFormatAmountException | O valor tem um formato inválido. |
notEnoughMoneyException | A carteira de origem não tem fundos suficientes. |
limitPerTransactionException | O valor excede o limite por transação. |
limitPerMonthException | A transação excede o limite mensal. |
walletDoesNotExist | A carteira da requisição não existe. |
walletCurrencyIncorrectException | A moeda da carteira não corresponde à requisição. |
recipientDoesNotExistException | A conta do destinatário não existe. |
paymentMethodNotAvailableForMerchantApi | O método de pagamento não está disponível para a sua API. |
resourceNotFound | O endpoint não existe. |
attemptsHaveEndedException | A conta esgotou o limite de requisições por hora. Veja Limite de requisições. |
tryAgainAfterAWhile | Os dados estão temporariamente bloqueados. Tente novamente mais tarde. |
serviceTemporaryUnavailable | Um serviço está temporariamente indisponível. Tente novamente mais tarde. |
internalServerError | Erro inesperado do servidor. |
Códigos de status HTTP
| Status | Significado |
|---|---|
400 | A 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. |
401 | Os 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). |
404 | O endpoint solicitado não foi encontrado. |
405 | O endpoint não aceita este método HTTP (httpMethodNotAllowed). |
409 | Os dados estão temporariamente bloqueados (tryAgainAfterAWhile). |
415 | O Content-Type da requisição não é suportado (unknownContentType). |
500 | Erro inesperado do servidor (internalServerError). |
503 | Um 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
errorIdde cada erro. - Verifique
errorFieldpara 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ê enviarsciName, a Volet.com rejeita uma segunda fatura com o mesmoorderIdpara esse Hosted Checkout.
Se ainda não estiver claro se um pagamento foi criado, fale com o suporte antes de enviá-lo novamente.
Relacionados
- Introdução — URL base, autenticação e formato das requisições
- Status — status de transações e de pagamentos