Erros Códigos de erro e como tratá-los na API DiamantePay
Quando uma requisição falha, a API retorna um objeto com a seguinte estrutura:
{ "message" : "Cobrança não encontrada" , "error" : "CHARGE_NOT_FOUND" , "status" : 404 } Campo Tipo Descrição messagestringMensagem descritiva em português errorstringCódigo de erro programático em inglês statusnumberCódigo HTTP da resposta
Código Significado Descrição 200OK Requisição bem-sucedida 201Created Recurso criado com sucesso 400Bad Request Dados inválidos ou parâmetros ausentes 401Unauthorized Autenticação ausente ou inválida 403Forbidden Sem permissão para acessar o recurso 404Not Found Recurso não encontrado 409Conflict Conflito (recurso já existe) 422Unprocessable Entity Erro de validação nos dados enviados 429Too Many Requests Limite de requisições excedido 500Internal Server Error Erro interno do servidor
Código Descrição UNAUTHORIZEDAutenticação ausente, token/chave inválida ou IP fora da whitelist INSUFFICIENT_PERMISSIONSem permissão para a ação solicitada NO_ACTIVE_MERCHANTNenhum merchant ativo selecionado API_KEY_REVOKEDChave de API foi revogada
Código Descrição RATE_LIMIT_EXCEEDEDLimite de requisições excedido
Código Descrição NOT_FOUNDRecurso não encontrado MERCHANT_ID_REQUIREDID do merchant é obrigatório CHARGE_NOT_FOUNDCobrança não encontrada WALLET_NOT_FOUNDCarteira não encontrada
Código Descrição IDEMPOTENCY_CONFLICTJá existe uma cobrança com a chave de idempotência informada BILLING_ADDRESS_REQUIREDEndereço de cobrança obrigatório para o método de pagamento informado PAYMENT_METHOD_NOT_ALLOWEDMétodo de pagamento não habilitado para a empresa CARD_FLOW_NOT_SUPPORTEDFluxo de cartão hospedado (card_flow: "hosted") não habilitado para o merchant/método informado CARD_FLOW_NOT_ROUTABLEO fluxo de orquestração ativo não roteia o fluxo hospedado para uma conexão com capability hosted — configure uma regra apontando para a conexão hospedada ou colete os dados do cartão no checkout CHARGE_AMOUNT_EXCEEDS_LIMITValor da cobrança excede o limite máximo permitido por transação para a empresa THREE_DS_REQUIREDAutenticação 3DS obrigatória para esta cobrança FRAUD_ANALYSIS_REQUIREDAnálise de fraude obrigatória para esta cobrança TOKEN_NOT_FOUNDToken de pagamento não encontrado NO_ACTIVE_ORCHESTRATOR_FLOWNenhum fluxo de orquestração ativo configurado ORCHESTRATOR_RESOLUTION_FAILEDErro interno ao resolver o fluxo de orquestração MERCHANT_WALLET_NOT_FOUNDEmpresa não possui carteira configurada SUBMERCHANT_WALLET_NOT_FOUNDSubmerchant não possui carteira configurada CHARGE_AUTHORIZATION_FAILEDPagamento recusado pela adquirente CHARGE_FAILEDFalha ao processar a cobrança FETCH_FAILEDFalha ao buscar a cobrança
Código Descrição CHARGE_ALREADY_CAPTUREDCobrança não pode ser capturada no estado atual CAPTURE_FAILEDFalha ao capturar a cobrança
Código Descrição CHARGE_ALREADY_REFUNDEDCobrança não pode ser estornada no estado atual REFUND_AMOUNT_EXCEEDS_CHARGEValor do estorno excede o valor da cobrança CHARGE_STATE_CHANGEDEstado da cobrança mudou durante o estorno REFUND_FAILEDFalha ao estornar a cobrança
Recomendamos sempre verificar o campo error da resposta antes de processar os dados:
const response = await fetch ( 'https://api.soarlabz.com/v1/charges' , { headers: { 'Authorization' : `Basic ${ credentials }` }, }); const result = await response. json (); if (result.error) { console. error
