Códigos de Erro

​

Visão Geral

• Um código de status HTTP indicando a categoria geral do erro
• Um código de erro específico que identifica a natureza exata do erro
• Uma mensagem de erro legível por humanos explicando o que deu errado
• Detalhes adicionais sobre o erro quando aplicável

• Depurar problemas de integração
• Implementar um tratamento de erro adequado em sua aplicação
• Fornecer feedback significativo aos usuários finais
• Manter um sistema de processamento de pagamentos robusto

​

Códigos de Erro da API Padrão

​

Formato da Resposta de Erro

{
  "code": "UNSUPPORTED_COUNTRY",
  "message": "Country AI currently not supported"
}

​

Referência de Códigos de Erro

• ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT
  • Gatilho: Ativações de chave de licença: novo limite < contagem de instâncias existente
  • Mensagem: O novo limite de ativação não pode ser menor que a contagem atual de instâncias
• ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Gatilho: Tentativa de adicionar complementos a assinaturas de cobrança baseadas em uso
  • Mensagem: Complementos em Assinaturas não são suportados para Cobrança Baseada em Uso
• ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
  • Gatilho: Tentativa de adicionar complementos a assinaturas sob demanda
  • Mensagem: Complementos não são permitidos para assinaturas sob demanda
• BRAND_MISMATCH
  • Gatilho: Itens do carrinho pertencem a marcas diferentes
  • Mensagem: Todos os itens no carrinho de produtos devem pertencer à mesma marca
• BRAND_NOT_ENABLED
  • Gatilho: Marca desativada ou não ativa
  • Mensagem: A marca fornecida não está habilitada
• BRAND_SUBMISSION_NOT_ENABLED
  • Gatilho: Reenvio de verificação de marca não habilitado
  • Mensagem: O reenvio de verificação de marca não está habilitado
• CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Gatilho: Tentativa de cobrar assinatura programada para cancelamento
  • Mensagem: Assinatura programada para cancelamento
• CHECKOUT_SESSION_CONSUMED
  • Gatilho: A sessão de checkout já gerou um pagamento
  • Mensagem: A sessão de checkout já foi consumida
• DISCOUNT_CODE_ALREADY_EXISTS
  • Gatilho: Criação de código de desconto duplicado
  • Mensagem: O código de desconto já existe
• DISCOUNT_CODE_EXPIRED
  • Gatilho: Código de desconto ultrapassou a data expires_at
  • Mensagem: Código de desconto expirado
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • Gatilho: Desconto reutilizado após usage_limit atingido
  • Mensagem: O limite de uso não pode ser menor que times_used / O código de desconto atingiu o limite de uso
• DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
  • Gatilho: Código aplicado a assinatura sob demanda
  • Mensagem: O cupom de desconto não está disponível para assinaturas sob demanda
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • Gatilho: Código aplicado a produto(s) não relacionados
  • Mensagem: O cupom de desconto não está disponível para este produto
• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • Gatilho: O mesmo item_id aparece duas vezes em items[]
  • Mensagem: IDs de item duplicados especificados na matriz de itens
• DUPLICATE_METER_IDS_IN_REQUEST
  • Gatilho: O mesmo ID de medidor aparece várias vezes na solicitação
  • Mensagem: IDs de medidor duplicados não são permitidos
• EXCHANGE_RATE_NOT_FOUND
  • Gatilho: Nenhuma taxa de câmbio para o par de moedas from → to
  • Mensagem: Taxa de câmbio não encontrada para converter de Moeda para Moeda
• EXISTING_REFUND_REQUEST_PROCESSING
  • Gatilho: Solicitação de reembolso anterior ainda está sendo processada
  • Mensagem: Uma solicitação de reembolso com status “Pendente” ainda está sendo processada
• INACTIVE_LICENSE_KEY
  • Gatilho: Status da chave ≠ ACTIVE
  • Mensagem: A chave de licença não está ativa
• INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
  • Gatilho: Mudança de plano em assinatura inativa
  • Mensagem: Mudar de planos não é suportado para assinaturas inativas
• INSUFFICIENT_WALLET_FUNDS
  • Gatilho: Saldo da carteira < valor de débito
  • Mensagem: Fundos insuficientes na carteira
• INTEGER_CONVERSION_FAILURE
  • Gatilho: Qualquer conversão de inteiro ↔ string/decimal que falha no servidor
  • Mensagem: Falha na Conversão de Inteiro
• INTERNAL_SERVER_ERROR
  • Gatilho: Exceções não capturadas; você deve registrar detalhes no servidor
  • Mensagem: Nenhuma mensagem pública (genérica 500)
• INVALID_DISCOUNT_CODE
  • Gatilho: Código não existe / não aplicável
  • Mensagem: Código de Desconto Inválido / Código de Desconto não pode ser aplicado a nenhum produto no carrinho
• INVALID_PERCENTAGE
  • Gatilho: Valor percentual > 100% (ou 10.000 pontos base)
  • Mensagem: O valor percentual não pode ser mais que 10000 / O valor do código de desconto não pode ser mais que 100%
• INVALID_QUANTITY
  • Gatilho: Quantidade inválida especificada para preços baseados em uso
  • Mensagem: Apenas 1 quantidade permitida em produtos de preço baseado em uso
• INVALID_QUERY_PARAMS
  • Gatilho: Parâmetros de consulta mutuamente exclusivos / malformados
  • Mensagem: Os parâmetros de consulta devem conter apenas time_frame ou (início, fim)
• INVALID_REQUEST_BODY
  • Gatilho: JSON malformado ou violação de esquema
  • Mensagem: O corpo da sua solicitação é inválido. Verifique os cabeçalhos e o objeto da sua solicitação.
• INVALID_REQUEST_PARAMETERS
  • Gatilho: Semântica errada (por exemplo, data no passado)
  • Mensagem: Não é possível alterar next_billing_date para um tempo passado
• INVALID_SUGGESTED_PRICE
  • Gatilho: Preço PWYW < preço mínimo permitido
  • Mensagem: O Preço Sugerido não pode ser menor que o preço mínimo. No caso de pagar o que você quiser, o preço é considerado como o valor mínimo aceito
• INVALID_TAX_ID
  • Gatilho: Validação de VAT/GST/TIN falhou
  • Mensagem: O ID fiscal é inválido
• LICENSE_KEY_LIMIT_REACHED
  • Gatilho: Ativações = limite
  • Mensagem: Limite de ativação da chave de licença atingido
• LICENSE_KEY_NOT_FOUND
  • Gatilho: ID de instância ou ID de chave inválido
  • Mensagem: Instância da chave de licença não encontrada ou não pertence a esta chave de licença
• LINE_ITEM_FULLY_REFUNDED
  • Gatilho: Tentativa de reembolsar item de linha já totalmente reembolsado
  • Mensagem: O item de linha foi totalmente reembolsado e não pode ser reembolsado novamente.
• LINE_ITEM_NOT_FOUND
  • Gatilho: ID do item não faz parte do pagamento referenciado
  • Mensagem: O item de linha não foi encontrado no pagamento
• LINE_ITEM_PRORATED
  • Gatilho: Reembolso ou atualização tentada em uma linha proporcional
  • Mensagem: O item de linha não pode ser reembolsado porque é proporcional
• LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
  • Gatilho: Valor do reembolso > valor pago (incluindo impostos)
  • Mensagem: O valor do reembolso solicitado para o item de linha incluindo impostos é , que está acima do valor pago
• LINE_ITEM_REFUND_AMOUNT_TOO_LOW
  • Gatilho: Valor do reembolso abaixo do limite mínimo
  • Mensagem: O valor do reembolso solicitado para o item de linha é , que é muito baixo
• MAXIMUM_KEYS_REACHED
  • Gatilho: Metadados / campos personalizados excederam 50 pares
  • Mensagem: Excede 50 pares chave-valor
• MERCHANT_NOT_LIVE
  • Gatilho: Negócio ainda em modo de teste/sandbox
  • Mensagem: O comerciante não está ativo
• METER_IS_DELETED
  • Gatilho: Tentativa de usar medidor excluído
  • Mensagem: O Medidor já foi excluído
• MISSING_ADDON_IDS
  • Gatilho: addon_id lista vazia ou IDs desconhecidos
  • Mensagem: Um ou mais IDs de produtos não existem:
• MISSING_METER_IDS
  • Gatilho: Lista de IDs de medidor vazia ou contém IDs inválidos
  • Mensagem: Um ou mais IDs de medidores não existem:
• MISSING_PRODUCT_INFORMATION
  • Gatilho: Produto existe, mas informações obrigatórias estão faltando
  • Mensagem: O produto existe, mas outras informações obrigatórias estão faltando ou são inválidas
• NEGATIVE_BALANCE_ADJUSTMENT
  • Gatilho: Tentativa de tornar o saldo da carteira negativo
  • Mensagem: O saldo da carteira não pode ser tornado negativo
• NO_ELIGIBLE_PAYMENT_METHODS
  • Gatilho: Após filtragem, nada ficou
  • Mensagem: Nenhum método de pagamento elegível encontrado
• NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
  • Gatilho: Tentativa de definir expiração em chave baseada em assinatura
  • Mensagem: Não é possível definir a data de expiração para chave de licença baseada em assinatura
• NOT_FOUND
  • Gatilho: Genérico 404 para qualquer recurso ausente
  • Mensagem: Item não encontrado (ou mais específico)
• ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
  • Gatilho: Troca de plano não permitida para sob demanda
  • Mensagem: Mudar de planos não é suportado para assinaturas sob demanda
• ON_DEMAND_SUBSCRIPTIONS_NOT_ENABLED
  • Gatilho: Negócio tem a flag de recurso desativada
  • Mensagem: Assinaturas sob demanda não habilitadas para este negócio
• ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Gatilho: Tentativa de usar sob demanda com cobrança baseada em uso
  • Mensagem: Assinaturas sob demanda não são suportadas para Cobrança Baseada em Uso
• PAY_AS_YOU_WANT_AMOUNT_REQUIRED
  • Gatilho: Preço ausente para produto PWYW
  • Mensagem: O valor é obrigatório para o produto pague o que quiser
• PAYMENT_ALREADY_REFUNDED
  • Gatilho: Reembolso duplicado
  • Mensagem: Este pagamento já foi reembolsado
• PAYMENT_HAS_BEEN_REFUNDED
  • Gatilho: O pagamento foi totalmente reembolsado
  • Mensagem: O ID do pagamento foi totalmente reembolsado.
• PAYMENT_NOT_SUCCEEDED
  • Gatilho: Tentativa de reembolsar/processar pagamento malsucedido
  • Mensagem: O pagamento fornecido não foi bem-sucedido
• PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Gatilho: Mudança de plano tentada em assinatura programada para cancelamento
  • Mensagem: Assinatura programada para cancelamento
• PREVIOUS_PAYMENT_PENDING
  • Gatilho: Tentativa de criar cobrança enquanto a anterior está em estado não terminal
  • Mensagem: Não é possível criar nova cobrança, pois o pagamento anterior ainda não foi bem-sucedido
• PRODUCT_CART_EMPTY
  • Gatilho: Carrinho de produtos vazio enviado
  • Mensagem: product_cart está vazio
• PRODUCT_IS_DELETED
  • Gatilho: Produto excluído logicamente
  • Mensagem: Sem mensagens
• REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT
  • Gatilho: Valor total do reembolso agregado > valor pago
  • Mensagem: O valor de reembolso calculado é maior que o valor pago
• REFUND_WINDOW_EXPIRED
  • Gatilho: Fora da janela de reembolso permitida
  • Mensagem: Reembolsos não podem ser iniciados dias após a criação do pagamento. Entre em contato com [email protected].
• REQUEST_AMOUNT_BELOW_MINIMUM
  • Gatilho: Valor < mínimo do produto
  • Mensagem: O valor não pode ser menor que o valor mínimo especificado para o produto
• SUBSCRIPTION_EXPIRED
  • Gatilho: Cobrança passada ends_at
  • Mensagem: Assinatura expirada, não é possível criar novas cobranças
• SUBSCRIPTION_INACTIVE
  • Gatilho: Status ≠ ACTIVE
  • Mensagem: Assinatura não está ativa
• SUBSCRIPTION_NOT_ON_DEMAND
  • Gatilho: Esperado sob demanda, mas obteve intervalo fixo
  • Mensagem: A assinatura já não está sob demanda
• SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
  • Gatilho: Tentativas de reembolso de pagamento de assinatura excederam o número máximo de tentativas
  • Mensagem: Limite máximo de 10 tentativas excedido para esta assinatura
• TOO_MANY_REQUESTS
  • Gatilho: Limite de taxa 429
  • Mensagem: Sem mensagens
• TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
  • Gatilho: Total combinado do carrinho < mínimo do gateway
  • Mensagem: Um valor mínimo de é necessário para processar o pagamento
• UNABLE_TO_EDIT_PRIMARY_BRAND
  • Gatilho: Tentativa de atualizar a marca primária via API regular
  • Mensagem: A marca primária não pode ser atualizada por este endpoint da API.
• UNAUTHORIZED
  • Gatilho: Sem chave de API ou token / escopo inválido
  • Mensagem: Você não está autorizado a realizar esta ação
• UNSUPPORTED_ACTION
  • Gatilho: Ação não suportada para tipo de recurso
  • Mensagem: Mudar de planos para assinaturas baseadas em uso não é suportado
• UNSUPPORTED_BILLING_CURRENCY
  • Gatilho: Assinaturas restritas a USD
  • Mensagem: Moeda de cobrança não USD não é suportada para assinaturas
• UNSUPPORTED_COUNTRY
  • Gatilho: Geo ainda não suportado
  • Mensagem: País atualmente não suportado
• UNSUPPORTED_CURRENCY
  • Gatilho: Moeda do produto ou complemento inválida
  • Mensagem: A moeda não é atualmente suportada / Apenas produtos USD e INR são suportados atualmente / Apenas USD e INR suportados para preço de complemento / Só é possível solicitar USD ou INR para billing_currency / Moeda não suportada / Moeda inesperada para assinaturas de cartão indiano
• UNSUPPORTED_DISCOUNT_TYPE
  • Gatilho: Descontos de valor fixo, etc., ainda não estão ativos
  • Mensagem: Apenas códigos de desconto percentual são suportados por enquanto
• UNSUPPORTED_PAYMENT_CURRENCY
  • Gatilho: Moeda de pagamento bloqueada para conector
  • Mensagem: Transação INR não é suportada para esta transação
• UNSUPPORTED_TAX_CATEGORY
  • Gatilho: String da categoria fiscal não está no enum
  • Mensagem: Categoria atualmente não suportada
• UNSUCCESSFUL_PAYMENT_ID
  • Gatilho: ID do pagamento referencia pagamento malsucedido
  • Mensagem: O ID do pagamento tem um status malsucedido.
• ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
  • Gatilho: Tentativa de reembolsar pagamento de valor zero
  • Mensagem: Não é possível reembolsar um pagamento com valor de moeda zero

​

Melhores Práticas

1. Sempre trate erros de forma elegante em sua aplicação
2. Implemente um registro de erros adequado
3. Use mensagens de erro apropriadas para os usuários finais
4. Implemente lógica de repetição para erros transitórios
5. Entre em contato com o suporte para problemas não resolvidos

​

Suporte