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

​

Autenticação & Conta

• UNAUTHORIZED
  • Trigger: Sem chave de API ou token/escopo inválido
  • Message: Você não está autorizado a realizar esta ação
• MERCHANT_NOT_LIVE
  • Trigger: Negócio ainda no modo de teste/sandbox
  • Message: O comerciante não está ativo

​

Pagamentos & Checkout

• CHECKOUT_SESSION_CONSUMED
  • Trigger: A sessão de checkout já gerou um pagamento
  • Message: A sessão de checkout já foi consumida
• NO_ELIGIBLE_PAYMENT_METHODS
  • Trigger: Após filtragem, nada restou
  • Message: Nenhum método de pagamento elegível encontrado
• PAYMENT_NOT_SUCCEEDED
  • Trigger: Tentativa de estorno/processamento de pagamento malsucedido
  • Message: O pagamento fornecido não foi bem-sucedido
• 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
• UNSUCCESSFUL_PAYMENT_ID
  • Trigger: ID de pagamento referência pagamento malsucedido
  • Message: O ID de Pagamento possui status malsucedido.

​

Conectores & BYOP

• BYOP_CONNECTOR_DISABLED
  • Trigger: Atualizando um método de pagamento em uma assinatura roteada através de um conector BYOP desativado
  • Message: A assinatura é roteada através do conector próprio do comerciante (BYOP) que atualmente está desativado
• BYOP_CUSTOM_INVOICE_ADDRESS_MISSING
  • Trigger: Um pagamento roteado pelo comerciante (BYOP) está faltando o endereço de fatura personalizado necessário
  • Message: O endereço de fatura personalizado BYOP é necessário quando um pagamento é roteado através do conector do comerciante
• CONNECTOR_LABEL_ALREADY_EXISTS
  • Trigger: Criando um conector com um rótulo que já existe
  • Message: Um conector com este rótulo já existe. Por favor, escolha um rótulo diferente.

​

Reembolsos

• 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
• LINE_ITEM_FULLY_REFUNDED
  • Trigger: Tentativa de reembolso de 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 de 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 uma linha rateada
  • Message: O item de linha não pode ser reembolsado porque é rateado
• LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
  • Trigger: Valor do reembolso > valor pago (imposto incl.)
  • Message: O valor do reembolso solicitado para o item de linha , incluindo imposto, é , o que está acima do valor pago
• LINE_ITEM_REFUND_AMOUNT_TOO_LOW
  • Trigger: Valor do reembolso abaixo do limite mínimo
  • Message: O valor do reembolso solicitado para o item de linha é , o que é muito baixo
• NOTHING_TO_REFUND
  • Trigger: Não resta valor reembolsável; todos os itens de linha positiva já foram totalmente reembolsados
  • Message: Não há valor reembolsável restante. Todos os itens de linha positiva foram totalmente reembolsados.
• PARTIAL_REFUND_NOT_ALLOWED
  • Trigger: Reembolso parcial tentado em um método de pagamento que só suporta reembolsos totais
  • Message: Reembolsos parciais não são permitidos para este método de pagamento
• 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 de Pagamento foi totalmente reembolsado.
• 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 de reembolso permitida
  • Message: Reembolsos não podem ser iniciados dias após a criação do pagamento. Entre em contato com support@dodopayments.com.
• ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
  • Trigger: Tentativa de reembolso de pagamento de valor zero
  • Message: Não é possível reembolsar um pagamento com valor de moeda zero

​

Assinaturas & Complementos

• ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Trigger: Tentativa de adicionar complementos a assinaturas de faturamento baseadas em uso
  • Message: Complementos em assinaturas não são suportados para faturamento baseado em uso
• ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
  • Trigger: Tentativa de adicionar complementos a assinaturas sob demanda
  • Message: Complementos não são permitidos para assinaturas sob demanda
• CANCEL_SCHEDULED_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Trigger: Portal do Cliente tenta cancelar uma mudança de plano agendada enquanto o negócio desativou essa ação
  • Message: Cancelar mudanças de plano agendadas está desativado para o portal do cliente.
• CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Trigger: Tentativa de cobrar assinatura agendada para cancelamento
  • Message: Assinatura agendada para cancelamento
• CUSTOMER_HAS_EXISTING_SUBSCRIPTION
  • Trigger: Criando uma assinatura para um cliente que já possui uma, quando várias assinaturas por cliente não são permitidas
  • Message: O cliente já possui uma assinatura existente. Para permitir várias assinaturas por cliente, altere as configurações de negócios
• DO_NOT_BILL_NOT_ALLOWED_IN_CUSTOMER_PORTAL
  • Trigger: do_not_bill modo de rateio usado em uma mudança de plano do Portal do Cliente
  • Message: modo de rateio não_faturar não é permitido no portal do cliente
• DUPLICATE_ADDON_IDS_IN_REQUEST
  • Trigger: O mesmo addon_id aparece mais de uma vez na solicitação
  • Message: IDs de complementos duplicados não são permitidos
• INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
  • Trigger: Mudança de plano em assinatura inativa
  • Message: Mudanças de plano não são suportadas para assinaturas inativas
• INVALID_PRORATION_MODE_WITH_NEXT_BILLING_DATE
  • Trigger: Um modo de rateio diferente de full_immediately usado com effective_at: next_billing_date
  • Message: Apenas o modo de rateio total_imediatamente é permitido com effective_at: next_billing_date
• MISSING_ADDON_IDS
  • Trigger: Lista addon_id vazia ou IDs desconhecidos
  • Message: Um ou mais IDs de produto não existem:
• ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
  • Trigger: Troca de plano não permitida para sob demanda
  • Message: Mudanças de plano não são suportadas para assinaturas sob demanda
• ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Trigger: Tentativa de usar sob demanda com faturamento baseado em uso
  • Message: Assinaturas Sob Demanda não são suportadas para Faturamento Baseado em Uso
• ONE_TIME_PRODUCTS_NOT_ALLOWED_FOR_ON_DEMAND
  • Trigger: Produto único adicionado a uma assinatura sob demanda
  • Message: Produtos únicos não são permitidos para assinaturas sob demanda
• PENDING_PLAN_CHANGE_EXISTS
  • Trigger: Nova mudança de plano solicitada enquanto uma anterior ainda está aguardando pagamento
  • Message: Já existe uma mudança de plano pendente para esta assinatura. Aguarde até que o pagamento atual seja concluído.
• PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Trigger: Mudança de plano via Portal do Cliente enquanto o negócio a desativou
  • Message: Mudança de plano de assinatura para portal do cliente está desativada.
• PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Trigger: Mudança de plano tentada em assinatura agendada para cancelamento
  • Message: Assinatura agendada para cancelamento
• SCHEDULE_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Trigger: Agendando uma mudança de plano via Portal do Cliente enquanto o negócio a desativou
  • Message: Agendamento de mudanças de plano está desativado para este negócio.
• SCHEDULED_PLAN_CHANGE_EXISTS
  • Trigger: Criando uma mudança de plano agendada quando uma já existe
  • Message: Já existe uma mudança de plano agendada para esta assinatura. Cancele a mudança agendada existente antes de criar uma nova.
• SCHEDULED_PLAN_CHANGE_NOT_FOUND
  • Trigger: Referenciando ou cancelando uma mudança de plano agendada que não existe
  • Message: Nenhuma mudança de plano agendada encontrada para esta assinatura.
• SUBSCRIPTION_EXPIRED
  • Trigger: Faturamento além ends_at
  • Message: Assinatura expirada não pode criar novas cobranças
• SUBSCRIPTION_INACTIVE
  • Trigger: Status ≠ ACTIVE
  • Message: A assinatura não está ativa
• SUBSCRIPTION_NOT_ON_DEMAND
  • Trigger: Esperado sob demanda, mas foi obtido intervalo fixo
  • Message: A assinatura já não está sob demanda
• SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
  • Trigger: Repetições de pagamento de assinatura excederam o máximo de tentativas
  • Message: Limite máximo de 10 tentativas de repetição excedido para esta assinatura

​

Produtos, Carrinho & Marcas

• BRAND_MISMATCH
  • Trigger: Itens do carrinho pertencem a diferentes marcas
  • Message: Todos os itens no carrinho de produtos devem pertencer à mesma marca
• BRAND_NOT_ENABLED
  • Trigger: Marca está desativada ou não está ativa
  • Message: A marca fornecida não está ativada
• BRAND_SUBMISSION_NOT_ENABLED
  • Trigger: Reenvio de verificação de marca não ativado
  • Message: O reenvio de verificação de marca não está ativado
• FILE_IN_USE
  • Trigger: Excluindo um arquivo de produto digital ainda referenciado por concessões de direito ativas (passe ?force=true para substituir)
  • Message: Arquivo digital é referenciado por concessões ativas
• 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 pagar o que você quiser, o preço é considerado o valor mínimo aceito
• LOCALIZED_PRICE_ALREADY_EXISTS
  • Trigger: Um preço localizado já existe para este produto e país/moeda
  • Message: Um preço localizado para este produto e país/moeda já existe
• LOCALIZED_PRICE_DUPLICATES_BASE
  • Trigger: O preço localizado duplica a moeda/país base do produto
  • Message: O preço localizado duplica a moeda/país base do produto
• LOCALIZED_PRICE_SHAPE_MISMATCH
  • Trigger: A forma de preço localizado não corresponde ao pricing_mode do produto
  • Message: A forma de preço localizado não corresponde ao pricing_mode do produto
• MISSING_PRODUCT_INFORMATION
  • Trigger: O produto existe, mas informações obrigatórias estão ausentes
  • Message: O produto existe, mas outras informações obrigatórias estão ausentes ou inválidas
• PAY_AS_YOU_WANT_AMOUNT_REQUIRED
  • Trigger: Falta preço para produto PWYW
  • Message: O valor é obrigatório para o produto pague o que você quiser
• PRODUCT_CART_EMTPY
  • Trigger: Carrinho de produtos vazio enviado
  • Message: product_cart está vazio (o código de erro é intencionalmente escrito como EMTPY para corresponder ao valor exato que a API retorna)
• PRODUCT_COLLECTION_IS_DELETED
  • Trigger: Operando em uma coleção de produtos que foi excluída
  • Message: Sem mensagem
• PRODUCT_COLLECTION_MUST_HAVE_PRODUCTS
  • Trigger: Removendo o último produto (ou último grupo com produtos) de uma coleção
  • Message: Não é possível excluir o último produto em uma coleção. Arquive a coleção em vez disso.
• PRODUCT_IS_DELETED
  • Trigger: Produto excluído temporariamente
  • Message: Sem mensagens
• PRODUCT_PRICING_MODE_REQUIRED
  • Trigger: Adicionando preços localizados antes de o pricing_mode do produto ser definido
  • Message: O pricing_mode do produto deve ser definido antes de adicionar preços localizados
• SLUG_ALREADY_TAKEN
  • Trigger: O slug/URL curto do produto solicitado já está em uso
  • Message: O slug já está em uso
• UNABLE_TO_EDIT_PRIMARY_BRAND
  • Trigger: Tentativa de atualizar a marca principal via API regular
  • Message: A marca principal não pode ser atualizada por este endpoint da API.

​

Descontos

• DISCOUNT_ALREADY_USED_ON_SUBSCRIPTION
  • Trigger: Reaplicando um desconto que já foi usado nesta assinatura
  • Message: Este desconto já foi usado nesta assinatura
• 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 passado sua data expires_at
  • Message: Código de desconto expirado
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • Trigger: Desconto reutilizado após usage_limit atingido
  • Message: Limite de uso não pode ser menor que times_used / Código de desconto atingiu o limite de uso
• DISCOUNT_NOT_APPLICABLE_TO_NEW_PRODUCT
  • Trigger: Mudança de plano para um produto ao qual o desconto existente não se aplica
  • Message: Desconto não aplicável ao produto do novo plano
• DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
  • Trigger: Código aplicado a assinatura sob demanda
  • Message: Cupom de desconto não disponível para assinaturas sob demanda
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • Trigger: Código aplicado a produtos não relacionados
  • Message: Cupom de desconto não disponível para este produto
• INVALID_DISCOUNT_CODE
  • Trigger: Código não existe/ não aplicável
  • Message: Código de Desconto Inválido / Código de Desconto não pode ser aplicado a nenhum produto no carrinho
• INVALID_PERCENTAGE
  • Trigger: Quantidade percentual > 100% (ou 10.000 pontos base)
  • Message: A quantia percentual não pode ser superior a 10000 / A quantia do código de desconto não pode ser superior a 100%
• UNSUPPORTED_DISCOUNT_TYPE
  • Trigger: Descontos de valor fixo, etc., ainda não estão disponíveis
  • Message: Apenas códigos de desconto percentuais são suportados por enquanto

​

Chaves de Licença

• ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT
  • Trigger: Ativações de chave de licença: novo limite < contagem atual de instâncias
  • Message: Novo limite de ativação não pode ser menor que a contagem atual de instâncias
• INACTIVE_LICENSE_KEY
  • Trigger: Status da chave ≠ ACTIVE
  • Message: A chave de licença não está ativa
• LICENSE_KEY_LIMIT_REACHED
  • Trigger: Ativações = limite
  • Message: Limite de ativação de chave de licença atingido
• LICENSE_KEY_NOT_FOUND
  • Trigger: ID de instância ou ID de chave inválido
  • Message: Instância de chave de licença não encontrada ou não pertence a esta chave de licença
• NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
  • Trigger: Tentativa de definir expiração em chave baseada em assinatura
  • Message: Não é possível definir a data de expiração para chave de licença baseada em assinatura

​

Faturamento Baseado no Uso & Medidores

• 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
• INVALID_QUANTITY
  • Trigger: Quantidade inválida especificada para precificação baseada em uso
  • Message: Apenas 1 quantidade permitida em produtos de preço baseado no uso
• METER_IS_DELETED
  • Trigger: Tentativa de usar medidor excluído
  • Message: O Medidor já foi excluído
• MISSING_METER_IDS
  • Trigger: Lista de IDs de medidores vazia ou contém IDs inválidos
  • Message: Um ou mais IDs de medidores não existem:

​

Faturamento Baseado em Crédito

• CREDIT_ENTITLEMENT_IS_DELETED
  • Trigger: Operando em uma concessão de crédito que foi excluída
  • Message: A concessão de crédito já foi excluída
• CREDIT_ENTITLEMENT_NAME_ALREADY_EXISTS
  • Trigger: Criando uma concessão de crédito com um nome que já existe
  • Message: Uma concessão de crédito com este nome já existe
• OVERAGE_LIMIT_EXCEEDED
  • Trigger: Um uso ou dedução de crédito excederia o limite de excesso configurado
  • Message: Limite de excesso excedido

​

Carteira

• INSUFFICIENT_WALLET_FUNDS
  • Trigger: Saldo da carteira < quantia de débito
  • Message: Fundos insuficientes na carteira
• NEGATIVE_BALANCE_ADJUSTMENT
  • Trigger: Tentativa de tornar o saldo da carteira negativo
  • Message: O saldo da carteira não pode ser negativo

​

Moeda, Imposto & Região

• EXCHANGE_RATE_NOT_FOUND
  • Trigger: Nenhuma taxa FX para o par de moedas from → to
  • Message: Taxa de câmbio não encontrada para converter de Moeda para Moeda
• INVALID_TAX_ID
  • Trigger: VAT/GST/TIN falhou na validação
  • Message: ID de Imposto é inválido
• REQUEST_AMOUNT_BELOW_MINIMUM
  • Trigger: Quantia < mínimo do produto
  • Message: A quantia não pode ser inferior ao montante mínimo especificado para o produto
• TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
  • Trigger: Total combinado do carrinho < mínimo do gateway
  • Message: Quantia mínima de é necessária para processar o pagamento
• UNSUPPORTED_BILLING_CURRENCY
  • Trigger: Assinaturas restritas ao USD
  • Message: Moeda de faturamento não USD não é suportada para assinaturas
• UNSUPPORTED_COUNTRY
  • Trigger: Geo ainda não suportado
  • Message: País atualmente não suportado
• UNSUPPORTED_CURRENCY
  • Trigger: Moeda de produto ou complemento inválida
  • Message: Moeda atualmente não suportada / Apenas produtos USD e INR suportados atualmente / Apenas USD e INR suportados para preço de complemento / Pode-se solicitar apenas USD ou INR para billing_currency / Moeda Não Suportada / Moeda inesperada para assinaturas de cartão indiano
• UNSUPPORTED_TAX_CATEGORY
  • Trigger: String de categoria de imposto não está no enum
  • Message: Categoria atualmente não suportada

​

Validação & Requisições

• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • Trigger: O mesmo item_id aparece duas vezes em items[]
  • Message: IDs de item duplicados especificados na matriz de items
• INVALID_QUERY_PARAMS
  • Trigger: Parâmetros de consulta mutuamente exclusivos / malformados
  • Message: Os parâmetros da consulta devem conter apenas time_frame ou (start, end)
• INVALID_REQUEST_BODY
  • Trigger: JSON malformado ou violação de esquema
  • Message: O corpo da requisição é inválido. Por favor, verifique seus cabeçalhos de requisição e objeto.
• INVALID_REQUEST_PARAMETERS
  • Trigger: Semântica errada (por exemplo, data no passado)
  • Message: Não é possível alterar next_billing_date para horário passado
• MAXIMUM_KEYS_REACHED
  • Trigger: Metadados / campos personalizados excederam 50 pares
  • Message: Excede 50 pares de chave-valor

​

Geral & Sistema

• INTEGER_CONVERSION_FAILURE
  • Trigger: Qualquer conversão integer ↔ string/decimal que falha do lado do servidor
  • Message: Falha de Conversão Inteira
• INTERNAL_SERVER_ERROR
  • Trigger: Exceções não capturadas; você deve registrar detalhes do lado do servidor
  • Message: Sem mensagem pública (genérico 500)
• NOT_FOUND
  • Trigger: 404 genérico para qualquer recurso ausente
  • Message: Item não encontrado (ou mais específico)
• TOO_MANY_REQUESTS
  • Trigger: 429 limite de taxa
  • Message: Sem mensagens
• UNSUPPORTED_ACTION
  • Trigger: Ação não suportada para tipo de recurso
  • Message: Mudanças de planos para assinaturas baseadas no uso não são suportadas

​

Melhores Práticas

1. Sempre gerencie erros de forma elegante em sua aplicação
2. Implemente registro adequado de erros
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