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
  • Trigger: Ativações da license key: novo limite < contagem de instâncias existentes
  • Message: O novo limite de ativações não pode ser menor que a contagem atual de instâncias
• ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Trigger: Tentativa de adicionar addons a assinaturas de Usage Based Billing
  • Message: Addons em assinaturas não são compatíveis com Usage Based Billing
• ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
  • Trigger: Tentativa de adicionar addons a assinaturas on-demand
  • Message: Addons não são permitidos para assinaturas on demand
• BRAND_MISMATCH
  • Trigger: Itens do carrinho pertencem a marcas diferentes
  • Message: Todos os itens no carrinho de produtos devem pertencer à mesma marca
• BRAND_NOT_ENABLED
  • Trigger: Marca está desabilitada ou não está ativa
  • Message: A marca fornecida não está habilitada
• BRAND_SUBMISSION_NOT_ENABLED
  • Trigger: Recurso de reenvio de verificação de marca não habilitado
  • Message: O reenvio de verificação da marca não está habilitado
• CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Trigger: Tentativa de cobrar assinatura programada para cancelamento
  • Message: Assinatura programada para cancelamento
• CHECKOUT_SESSION_CONSUMED
  • Trigger: Sessão de checkout já gerou um pagamento
  • Message: Sessão de checkout já foi consumida
• DISCOUNT_CODE_ALREADY_EXISTS
  • Trigger: Criação de código de desconto duplicado
  • Message: O código de desconto já existe
• DISCOUNT_CODE_EXPIRED
  • Trigger: Código de desconto passou da data expires_at
  • Message: Código de desconto expirou
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • Trigger: Código de desconto reutilizado após usage_limit atingido
  • Message: 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
  • Trigger: Código aplicado a assinatura on-demand
  • Message: Cupom de desconto não está disponível para assinaturas on demand
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • Trigger: Código aplicado a produto(s) não relacionado(s)
  • Message: Cupom de desconto não está disponível para este produto
• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • Trigger: O mesmo item_id aparece duas vezes em items[]
  • Message: item_ids duplicados especificados no array items
• DUPLICATE_METER_IDS_IN_REQUEST
  • Trigger: O mesmo ID de medidor aparece várias vezes na requisição
  • Message: IDs de medidor duplicados não são permitidos
• EXCHANGE_RATE_NOT_FOUND
  • Trigger: Sem taxa de câmbio (FX) para o par de moedas from → to
  • Message: Taxa de câmbio não encontrada para converter de Currency para Currency
• EXISTING_REFUND_REQUEST_PROCESSING
  • Trigger: Solicitação de reembolso anterior ainda está sendo processada
  • Message: Uma solicitação de reembolso com status “Pending” ainda está sendo processada
• INACTIVE_LICENSE_KEY
  • Trigger: Status da chave ≠ ACTIVE
  • Message: A chave de licença não está ativa
• INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
  • Trigger: Alteração de plano em assinatura inativa
  • Message: Alterar planos não é compatível com assinaturas inativas
• INSUFFICIENT_WALLET_FUNDS
  • Trigger: Saldo da carteira < valor do débito
  • Message: Fundos insuficientes na carteira
• INTEGER_CONVERSION_FAILURE
  • Trigger: Qualquer conversão de inteiro ↔ string/decimal que falha no servidor
  • Message: Falha na conversão de inteiro
• INTERNAL_SERVER_ERROR
  • Trigger: Exceções não tratadas; você deve registrar os detalhes no servidor
  • Message: Sem mensagem pública (erro genérico 500)
• INVALID_DISCOUNT_CODE
  • Trigger: Código não existe / não é aplicável
  • Message: Código de desconto inválido / O código de desconto não pode ser aplicado a nenhum produto no carrinho
• INVALID_PERCENTAGE
  • Trigger: Percentual > 100% (ou 10.000 pontos-base)
  • Message: O percentual não pode ser maior que 10000 / O valor do código de desconto não pode ser maior que 100%
• INVALID_QUANTITY
  • Trigger: Quantidade inválida especificada para precificação baseada em uso
  • Message: Apenas 1 quantidade é permitida em produtos com preço baseado em uso
• INVALID_QUERY_PARAMS
  • Trigger: Parâmetros de consulta mutuamente exclusivos / malformados
  • Message: Os parâmetros de consulta devem conter apenas time_frame ou (start, end)
• INVALID_REQUEST_BODY
  • Trigger: JSON malformado ou violação de esquema
  • Message: Seu corpo de requisição é inválido. Por favor, verifique seus cabeçalhos e objeto de requisição.
• INVALID_REQUEST_PARAMETERS
  • Trigger: Semântica incorreta (por exemplo, data no passado)
  • Message: Não é possível alterar next_billing_date para um horário no passado
• INVALID_SUGGESTED_PRICE
  • Trigger: Preço PWYW < preço mínimo permitido
  • Message: O Preço Sugerido não pode ser inferior ao preço mínimo. No caso de pay what you want, o valor é considerado como o montante mínimo aceito
• INVALID_TAX_ID
  • Trigger: VAT/GST/TIN falhou na validação
  • Message: O identificador fiscal é inválido
• LICENSE_KEY_LIMIT_REACHED
  • Trigger: Ativações = limite
  • Message: Limite de ativações da license key atingido
• LICENSE_KEY_NOT_FOUND
  • Trigger: ID da instância ou ID da chave inválido
  • Message: Instância da license key não encontrada ou não pertence a esta license key
• LINE_ITEM_FULLY_REFUNDED
  • Trigger: Tentativa de reembolsar item de linha já totalmente reembolsado
  • Message: O item de linha foi totalmente reembolsado e não pode ser reembolsado novamente.
• LINE_ITEM_NOT_FOUND
  • Trigger: ID do item não faz parte do pagamento referenciado
  • Message: Item de linha não encontrado no pagamento
• LINE_ITEM_PRORATED
  • Trigger: Tentativa de reembolso ou atualização em item proporcional
  • Message: O item de linha não pode ser reembolsado porque é proporcional
• LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
  • Trigger: Valor do reembolso > valor pago (com impostos)
  • Message: O valor de reembolso solicitado para o item de linha , incluindo impostos, é , o que excede o valor pago
• LINE_ITEM_REFUND_AMOUNT_TOO_LOW
  • Trigger: Valor do reembolso abaixo do limite mínimo
  • Message: O valor de reembolso solicitado para o item de linha é , o que é muito baixo
• MAXIMUM_KEYS_REACHED
  • Trigger: Metadados / campos personalizados excederam 50 pares
  • Message: Excede 50 pares chave-valor
• MERCHANT_NOT_LIVE
  • Trigger: Empresa ainda em modo de teste/sandbox
  • Message: O comerciante não está ativo
• METER_IS_DELETED
  • Trigger: Tentativa de usar medidor excluído
  • Message: O medidor já foi excluído
• MISSING_ADDON_IDS
  • Trigger: Lista addon_id vazia ou IDs desconhecidos
  • Message: Um ou mais IDs de produto não existem:
• MISSING_METER_IDS
  • Trigger: Lista de IDs de medidor vazia ou contém IDs inválidos
  • Message: Um ou mais IDs de medidor não existem:
• MISSING_PRODUCT_INFORMATION
  • Trigger: Produto existe, mas informações obrigatórias ausentes
  • Message: O produto existe, mas outras informações obrigatórias estão ausentes ou inválidas
• NEGATIVE_BALANCE_ADJUSTMENT
  • Trigger: Tentativa de deixar saldo da carteira negativo
  • Message: Não é permitido tornar o saldo da carteira negativo
• NO_ELIGIBLE_PAYMENT_METHODS
  • Trigger: Após o filtro, nada sobrou
  • Message: Nenhum método de pagamento elegível encontrado
• NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
  • Trigger: Tentativa de definir expiração em chave baseada em assinatura
  • Message: Não é possível definir data de expiração para license key baseada em assinatura
• NOT_FOUND
  • Trigger: 404 genérico para qualquer recurso ausente
  • Message: Item não encontrado (ou mais específico)
• ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
  • Trigger: Troca de plano não permitida para on-demand
  • Message: Alterar planos não é compatível com assinaturas on demand
• ON_DEMAND_SUBSCRIPTIONS_NOT_ENABLED
  • Trigger: Empresa com flag de recurso desativado
  • Message: Assinaturas on demand não estão habilitadas para esta empresa
• ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Trigger: Tentativa de usar on-demand com Usage Based Billing
  • Message: Assinaturas On Demand não são compatíveis com Usage Based Billing
• PAY_AS_YOU_WANT_AMOUNT_REQUIRED
  • Trigger: Falta de preço para produto PWYW
  • Message: O valor é obrigatório para produtos pay as you want
• PAYMENT_ALREADY_REFUNDED
  • Trigger: Reembolso duplicado
  • Message: Este pagamento já foi reembolsado
• PAYMENT_HAS_BEEN_REFUNDED
  • Trigger: Pagamento já foi totalmente reembolsado
  • Message: O ID do pagamento foi totalmente reembolsado.
• PAYMENT_NOT_SUCCEEDED
  • Trigger: Tentativa de reembolsar/processar pagamento sem sucesso
  • Message: O pagamento fornecido não teve sucesso
• PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Trigger: Tentativa de alteração de plano em assinatura programada para cancelamento
  • Message: Assinatura programada para cancelamento
• PREVIOUS_PAYMENT_PENDING
  • Trigger: Tentativa de criar cobrança enquanto a anterior está em estado não terminal
  • Message: Não é possível criar nova cobrança pois o pagamento anterior ainda não foi bem-sucedido
• PRODUCT_CART_EMPTY
  • Trigger: Carrinho de produtos vazio enviado
  • Message: product_cart está vazio
• PRODUCT_IS_DELETED
  • Trigger: Produto marcado como excluído (soft-deleted)
  • Message: Sem mensagens
• REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT
  • Trigger: Valor agregado do reembolso > valor pago
  • Message: O valor calculado do reembolso é maior que o valor pago
• REFUND_WINDOW_EXPIRED
  • Trigger: Fora da janela permitida de reembolso
  • Message: Reembolsos não podem ser iniciados dias após a criação do pagamento. Entre em contato com support@dodopayments.com.
• REQUEST_AMOUNT_BELOW_MINIMUM
  • Trigger: Valor < mínimo do produto
  • Message: O valor não pode ser menor que o mínimo especificado para o produto
• SUBSCRIPTION_EXPIRED
  • Trigger: Faturamento além de ends_at
  • Message: Assinatura expirada não pode gerar novas cobranças
• SUBSCRIPTION_INACTIVE
  • Trigger: Status ≠ ACTIVE
  • Message: Assinatura não está ativa
• SUBSCRIPTION_NOT_ON_DEMAND
  • Trigger: Esperava on-demand, mas recebeu intervalo fixo
  • Message: A assinatura já não é on demand
• SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
  • Trigger: Tentativas de pagamento da assinatura excederam o máximo de tentativas
  • Message: Limite máximo de 10 tentativas excedido para esta assinatura
• TOO_MANY_REQUESTS
  • Trigger: Limite de taxa 429
  • Message: Sem mensagens
• TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
  • Trigger: Total combinado do carrinho < mínimo do gateway
  • Message: É necessário um valor mínimo de para processar o pagamento
• UNABLE_TO_EDIT_PRIMARY_BRAND
  • Trigger: Tentativa de atualizar marca primária via API regular
  • Message: A marca primária não pode ser atualizada por este endpoint da API.
• UNAUTHORIZED
  • Trigger: Sem chave de API ou token / escopo inválido
  • Message: Você não está autorizado a realizar esta ação
• UNSUPPORTED_ACTION
  • Trigger: Ação não suportada para o tipo de recurso
  • Message: Alterar planos para assinaturas baseadas em uso não é compatível
• UNSUPPORTED_BILLING_CURRENCY
  • Trigger: Assinaturas restritas ao USD
  • Message: Moeda de cobrança diferente de USD não é compatível com assinaturas
• UNSUPPORTED_COUNTRY
  • Trigger: Região ainda não suportada
  • Message: País atualmente não é suportado
• UNSUPPORTED_CURRENCY
  • Trigger: Moeda do produto ou addon inválida
  • Message: A moeda não é compatível no momento / Somente produtos em USD e INR são suportados atualmente / Somente USD e INR são suportados para o preço do addon / Só é possível solicitar USD ou INR para billing_currency / Moeda não suportada / Moeda inesperada para assinaturas com cartão indiano
• UNSUPPORTED_DISCOUNT_TYPE
  • Trigger: Descontos de valor fixo, etc., ainda não ativos
  • Message: Somente códigos de desconto percentuais são suportados por enquanto
• UNSUPPORTED_PAYMENT_CURRENCY
  • Trigger: Moeda de pagamento bloqueada para o conector
  • Message: Transações em INR não são compatíveis para esta transação
• UNSUPPORTED_TAX_CATEGORY
  • Trigger: String da categoria fiscal não está no enum
  • Message: Categoria atualmente não é suportada
• UNSUCCESSFUL_PAYMENT_ID
  • Trigger: ID do pagamento referencia um pagamento sem sucesso
  • Message: O ID do pagamento possui um status sem sucesso.
• ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
  • Trigger: Tentativa de reembolsar pagamento com valor zero
  • Message: Não é possível reembolsar um pagamento com valor monetário 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