Códigos de Error

​

Descripción General

• Un código de estado HTTP que indica la categoría general del error
• Un código de error específico que identifica la naturaleza exacta del error
• Un mensaje de error legible por humanos que explica qué salió mal
• Detalles adicionales sobre el error cuando sea aplicable

• Depurar problemas de integración
• Implementar un manejo de errores adecuado en su aplicación
• Proporcionar retroalimentación significativa a los usuarios finales
• Mantener un sistema de procesamiento de pagos robusto

​

Códigos de Error de API Estándar

​

Formato de Respuesta de Error

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

​

Referencia de Códigos de Error

​

Autenticación & Cuenta

• UNAUTHORIZED
  • Desencadenante: No hay clave API o token/scope inválido
  • Mensaje: No está autorizado para realizar esta acción
• MERCHANT_NOT_LIVE
  • Desencadenante: Negocio todavía en modo prueba/sandbox
  • Mensaje: El comerciante no está en vivo

​

Pagos & Checkout

• CHECKOUT_SESSION_CONSUMED
  • Desencadenante: La sesión de checkout ya ha generado un pago
  • Mensaje: La sesión de checkout ya ha sido consumida
• NO_ELIGIBLE_PAYMENT_METHODS
  • Desencadenante: Después de filtrar, no queda nada
  • Mensaje: No se encontraron métodos de pago elegibles
• PAYMENT_NOT_SUCCEEDED
  • Desencadenante: Intento de reembolsar/procesar pago no exitoso
  • Mensaje: El pago proporcionado no ha tenido éxito
• PREVIOUS_PAYMENT_PENDING
  • Desencadenante: Intento de crear un cargo mientras el anterior está en estado no terminal
  • Mensaje: No se puede crear un nuevo cargo ya que el pago anterior aún no es exitoso
• UNSUCCESSFUL_PAYMENT_ID
  • Desencadenante: ID de pago referencia a un pago no exitoso
  • Mensaje: El ID de Pago tiene un estado no exitoso.

​

Conectores & BYOP

• BYOP_CONNECTOR_DISABLED
  • Desencadenante: Actualización de un método de pago en una suscripción enrutada a través de un conector BYOP deshabilitado
  • Mensaje: La suscripción está enrutada a través del conector propio (BYOP) del comerciante, el cual está deshabilitado
• BYOP_CUSTOM_INVOICE_ADDRESS_MISSING
  • Desencadenante: Un pago enrutado por el comerciante (BYOP) carece de la dirección de factura personalizada requerida
  • Mensaje: Se requiere una dirección de factura personalizada BYOP cuando un pago se enruta a través del conector del comerciante
• CONNECTOR_LABEL_ALREADY_EXISTS
  • Desencadenante: Creación de un conector con una etiqueta que ya existe
  • Mensaje: Ya existe un conector con esta etiqueta. Por favor, elija una etiqueta diferente.

​

Reembolsos

• EXISTING_REFUND_REQUEST_PROCESSING
  • Trigger: Solicitud de reembolso anterior aún en proceso
  • Message: Una solicitud de reembolso con estado “Pending” aún está en proceso
• LINE_ITEM_FULLY_REFUNDED
  • Desencadenante: Intento de reembolsar un ítem ya completamente reembolsado
  • Mensaje: El ítem ha sido completamente reembolsado y no se puede reembolsar más.
• LINE_ITEM_NOT_FOUND
  • Desencadenante: ID de ítem no parte del pago referenciado
  • Mensaje: Ítem no encontrado en el pago
• LINE_ITEM_PRORATED
  • Desencadenante: Reembolso o actualización intentada en una línea prorrateada
  • Mensaje: El ítem no se puede reembolsar porque está prorrateado
• LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
  • Desencadenante: El monto del reembolso > monto pagado (incl. impuestos)
  • Mensaje: El ítem solicitó un monto de reembolso incluidos impuestos de que supera el monto pagado
• LINE_ITEM_REFUND_AMOUNT_TOO_LOW
  • Desencadenante: Monto del reembolso por debajo del umbral mínimo
  • Mensaje: El ítem solicitó un monto de reembolso de que es demasiado bajo
• NOTHING_TO_REFUND
  • Desencadenante: No queda ningún monto reembolsable; todos los ítems positivos ya han sido completamente reembolsados
  • Mensaje: No queda ningún monto reembolsable. Todos los ítems positivos han sido completamente reembolsados.
• PARTIAL_REFUND_NOT_ALLOWED
  • Desencadenante: Intento de reembolso parcial con un método de pago que solo admite reembolsos completos
  • Mensaje: No se permiten reembolsos parciales para este método de pago
• PAYMENT_ALREADY_REFUNDED
  • Desencadenante: Reembolso duplicado
  • Mensaje: Este pago ya ha sido reembolsado
• PAYMENT_HAS_BEEN_REFUNDED
  • Desencadenante: El pago ha sido completamente reembolsado
  • Mensaje: El ID de Pago ha sido completamente reembolsado.
• REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT
  • Desencadenante: Monto agregado del reembolso > monto pagado
  • Mensaje: El monto calculado del reembolso es mayor que el monto pagado
• REFUND_WINDOW_EXPIRED
  • Desencadenante: Fuera del periodo permitido para reembolso
  • Mensaje: No se pueden iniciar reembolsos días después de la creación del pago. Contacte support@dodopayments.com.
• ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
  • Desencadenante: Intento de reembolsar pago de monto cero
  • Mensaje: No se puede reembolsar un pago con cantidad monetaria cero

​

Suscripciones & Complementos

• ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Desencadenante: Intento de añadir complementos a suscripciones basadas en uso
  • Mensaje: No se admiten complementos en suscripciones basadas en uso
• ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
  • Desencadenante: Intento de añadir complementos a suscripciones a demanda
  • Mensaje: No se permiten complementos para suscripciones a demanda
• CANCEL_SCHEDULED_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Desencadenante: El portal de clientes intenta cancelar un cambio de plan programado mientras el negocio ha desactivado esa acción
  • Mensaje: La cancelación del cambio de plan programado está deshabilitada para el portal del cliente.
• CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Desencadenante: Intento de cobrar una suscripción programada para cancelación
  • Mensaje: Suscripción programada para cancelación
• CUSTOMER_HAS_EXISTING_SUBSCRIPTION
  • Desencadenante: Creación de una suscripción para un cliente que ya tiene una, cuando no se permiten múltiples suscripciones por cliente
  • Mensaje: El cliente ya tiene una suscripción. Para permitir múltiples suscripciones por cliente, cambia la configuración del negocio
• DO_NOT_BILL_NOT_ALLOWED_IN_CUSTOMER_PORTAL
  • Desencadenante: do_not_bill modo prorrateo usado en un cambio de plan del Portal del Cliente
  • Mensaje: El modo prorrateo do_not_bill no está permitido en el portal del cliente
• DUPLICATE_ADDON_IDS_IN_REQUEST
  • Desencadenante: addon_id aparece más de una vez en la solicitud
  • Mensaje: No se permiten IDs de complementos duplicados
• INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
  • Desencadenante: Cambio de plan en suscripción inactiva
  • Mensaje: No se admiten cambios de planes para suscripciones inactivas
• INVALID_PRORATION_MODE_WITH_NEXT_BILLING_DATE
  • Desencadenante: Un modo de prorrateo distinto a full_immediately usado con effective_at: next_billing_date
  • Mensaje: Solo se permite el modo de prorrateo full_immediately con effective_at: next_billing_date
• MISSING_ADDON_IDS
  • Desencadenante: Lista addon_id vacía o con IDs desconocidos
  • Mensaje: Uno o más IDs de producto no existen:
• ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
  • Desencadenante: Cambio de plan no permitido para a demanda
  • Mensaje: No se admiten cambios de planes para suscripciones a demanda
• ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Desencadenante: Intento de usar a demanda con facturación basada en uso
  • Mensaje: No se admiten suscripciones a demanda para facturación basada en uso
• ONE_TIME_PRODUCTS_NOT_ALLOWED_FOR_ON_DEMAND
  • Desencadenante: Producto de una sola vez añadido a una suscripción a demanda
  • Mensaje: No se permiten productos de una sola vez para suscripciones a demanda
• PENDING_PLAN_CHANGE_EXISTS
  • Desencadenante: Nuevo cambio de plan solicitado mientras uno anterior aún está esperando pago
  • Mensaje: Ya existe un cambio de plan pendiente para esta suscripción. Por favor, espere a que se complete el pago actual.
• PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Desencadenante: Cambio de plan vía Portal del Cliente mientras el negocio lo ha desactivado
  • Mensaje: El cambio de plan de suscripción para el portal del cliente está deshabilitado.
• PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Desencadenante: Cambio de plan intentado en suscripción programada para cancelación
  • Mensaje: Suscripción programada para cancelación
• SCHEDULE_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Desencadenante: Programación de un cambio de plan vía Portal del Cliente mientras el negocio lo ha desactivado
  • Mensaje: La programación de cambios de planes está deshabilitada para este negocio.
• SCHEDULED_PLAN_CHANGE_EXISTS
  • Desencadenante: Creación de un cambio de plan programado cuando ya existe uno
  • Mensaje: Ya existe un cambio de plan programado para esta suscripción. Por favor cancele el cambio programado existente antes de crear uno nuevo.
• SCHEDULED_PLAN_CHANGE_NOT_FOUND
  • Desencadenante: Referencia o cancelación de un cambio de plan programado que no existe
  • Mensaje: No se ha encontrado ningún cambio de plan programado para esta suscripción.
• SUBSCRIPTION_EXPIRED
  • Desencadenante: Facturación pasada ends_at
  • Mensaje: La suscripción expiró y no se pueden crear nuevos cargos
• SUBSCRIPTION_INACTIVE
  • Desencadenante: Estado ≠ ACTIVE
  • Mensaje: La suscripción no está activa
• SUBSCRIPTION_NOT_ON_DEMAND
  • Desencadenante: Se esperaba a demanda pero se obtuvo intervalo fijo
  • Mensaje: La suscripción ya no es a demanda
• SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
  • Desencadenante: Los reintentos de pago de la suscripción excedieron el máximo de intentos
  • Mensaje: El límite máximo de 10 intentos ha sido excedido para esta suscripción

​

Productos, Carrito & Marcas

• BRAND_MISMATCH
  • Desencadenante: Los ítems del carrito pertenecen a diferentes marcas
  • Mensaje: Todos los ítems en el carrito de productos deben pertenecer a la misma marca
• BRAND_NOT_ENABLED
  • Desencadenante: La marca está deshabilitada o no activa
  • Mensaje: La marca proporcionada no está habilitada
• BRAND_SUBMISSION_NOT_ENABLED
  • Desencadenante: Función de reenvío de verificación de marca no habilitada
  • Mensaje: El reenvío de verificación de marca no está habilitado
• FILE_IN_USE
  • Desencadenante: Eliminación de un archivo de producto digital aún referido por concesiones de derechos activas (pase ?force=true para anular)
  • Mensaje: El archivo digital está referenciado por concesiones activas
• INVALID_SUGGESTED_PRICE
  • Desencadenante: Precio PWYW < precio mínimo permitido
  • Mensaje: El precio sugerido no puede ser inferior al precio mínimo. En caso de pago lo que quieras, el precio se considera como el monto mínimo aceptado
• LOCALIZED_PRICE_ALREADY_EXISTS
  • Desencadenante: Ya existe un precio localizado para este producto y país/moneda
  • Mensaje: Ya existe un precio localizado para este producto y país/moneda
• LOCALIZED_PRICE_DUPLICATES_BASE
  • Desencadenante: El precio localizado duplica la moneda/país base del producto
  • Mensaje: El precio localizado duplica la moneda/país base del producto
• LOCALIZED_PRICE_SHAPE_MISMATCH
  • Desencadenante: La forma del precio localizado no coincide con pricing_mode del producto
  • Mensaje: La forma del precio localizado no coincide con el pricing_mode del producto
• MISSING_PRODUCT_INFORMATION
  • Desencadenante: El producto existe pero falta información obligatoria
  • Mensaje: El producto existe pero falta otra información obligatoria o es inválida
• PAY_AS_YOU_WANT_AMOUNT_REQUIRED
  • Desencadenante: Falta el precio para el producto PWYW
  • Mensaje: El monto es obligatorio para el producto de paga lo que quieras
• PRODUCT_CART_EMTPY
  • Desencadenante: Carrito de productos vacío enviado
  • Mensaje: el carrito_de_productos está vacío (el código de error está intencionadamente escrito EMTPY para que coincida con el valor exacto que devuelve el API)
• PRODUCT_COLLECTION_IS_DELETED
  • Desencadenante: Operando sobre una colección de productos que ha sido eliminada
  • Mensaje: Sin mensaje
• PRODUCT_COLLECTION_MUST_HAVE_PRODUCTS
  • Desencadenante: Eliminación del último producto (o último grupo con productos) de una colección
  • Mensaje: No se puede eliminar el último producto de una colección. Archiva la colección en su lugar.
• PRODUCT_IS_DELETED
  • Desencadenante: Producto eliminado suavemente
  • Mensaje: Sin mensajes
• PRODUCT_PRICING_MODE_REQUIRED
  • Desencadenante: Añadiendo precios localizados antes de que se establezca pricing_mode del producto
  • Mensaje: El modo de fijación de precios del producto debe establecerse antes de añadir precios localizados
• SLUG_ALREADY_TAKEN
  • Desencadenante: El slug/corto URL del producto solicitado ya está en uso
  • Mensaje: El slug ya está tomado
• UNABLE_TO_EDIT_PRIMARY_BRAND
  • Desencadenante: Intento de actualizar la marca principal a través del API regular
  • Mensaje: La marca principal no se puede actualizar a través de este endpoint del API.

​

Descuentos

• DISCOUNT_ALREADY_USED_ON_SUBSCRIPTION
  • Desencadenante: Reaplicación de un descuento que ya ha sido usado en esta suscripción
  • Mensaje: Este descuento ya ha sido usado en esta suscripción
• DISCOUNT_CODE_ALREADY_EXISTS
  • Desencadenante: Creación de código de descuento duplicado
  • Mensaje: El código de descuento ya existe
• DISCOUNT_CODE_EXPIRED
  • Desencadenante: Código de descuento pasado su fecha expires_at
  • Mensaje: El código de descuento ha expirado
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • Desencadenante: El descuento se reutiliza después de que se alcance usage_limit
  • Mensaje: El límite de uso no puede ser menor que el times_used / Código de descuento alcanzó el límite de uso
• DISCOUNT_NOT_APPLICABLE_TO_NEW_PRODUCT
  • Desencadenante: Cambio de plan a un producto al que no se aplica el descuento existente
  • Mensaje: El descuento no es aplicable al producto del nuevo plan
• DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
  • Desencadenante: Código aplicado a suscripción a demanda
  • Mensaje: El cupón de descuento no está disponible para suscripciones a demanda
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • Desencadenante: Código aplicado a producto(s) no relacionado(s)
  • Mensaje: El cupón de descuento no está disponible para este producto
• INVALID_DISCOUNT_CODE
  • Desencadenante: El código no existe/no es aplicable
  • Mensaje: Código de descuento inválido / Código de descuento no puede aplicarse a ningún producto en el carrito
• INVALID_PERCENTAGE
  • Desencadenante: Monto por porcentaje > 100% (o 10,000 puntos básicos)
  • Mensaje: La cantidad de porcentaje no puede ser más de 10000 / El monto del código de descuento no puede ser más de 100%
• UNSUPPORTED_DISCOUNT_TYPE
  • Desencadenante: Descuentos de cantidad fija, etc., aún no en vivo
  • Mensaje: Solo se admiten códigos de descuento de porcentaje por ahora

​

Claves de Licencia

• ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT
  • Desencadenante: Activaciones de clave de licencia: nuevo límite < cantidad existente de instancias
  • Mensaje: El nuevo límite de activación no puede ser menor que el conteo actual de instancias
• INACTIVE_LICENSE_KEY
  • Desencadenante: Estado de la clave ≠ ACTIVE
  • Mensaje: La clave de licencia no está activa
• LICENSE_KEY_LIMIT_REACHED
  • Desencadenante: Activaciones = límite
  • Mensaje: Se ha alcanzado el límite de activación de la clave de licencia
• LICENSE_KEY_NOT_FOUND
  • Desencadenante: ID de instancia o ID de clave inválido
  • Mensaje: No se encontró la instancia de clave de licencia o no pertenece a esta clave de licencia
• NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
  • Desencadenante: Intento de establecer vencimiento en clave basada en sub
  • Mensaje: No se puede establecer la fecha de vencimiento para la clave de licencia basada en suscripción

​

Facturación Basada en Uso & Medidores

• DUPLICATE_METER_IDS_IN_REQUEST
  • Desencadenante: El mismo ID de medidor aparece varias veces en la solicitud
  • Mensaje: No se permiten IDs de medidor duplicados
• INVALID_QUANTITY
  • Desencadenante: Cantidad inválida especificada para precios basados en uso
  • Mensaje: Solo se permite 1 cantidad en productos de precio basado en uso
• METER_IS_DELETED
  • Desencadenante: Intento de usar medidor eliminado
  • Mensaje: El medidor ya ha sido eliminado
• MISSING_METER_IDS
  • Desencadenante: Lista de IDs de medidor vacía o contiene IDs inválidos
  • Mensaje: Uno o más IDs de medidor no existen:

​

Facturación Basada en Crédito

• CREDIT_ENTITLEMENT_IS_DELETED
  • Desencadenante: Operando sobre una concesión de crédito que ha sido eliminada
  • Mensaje: La concesión de crédito ya ha sido eliminada
• CREDIT_ENTITLEMENT_NAME_ALREADY_EXISTS
  • Desencadenante: Creación de una concesión de crédito con un nombre que ya existe
  • Mensaje: Ya existe una concesión de crédito con este nombre
• OVERAGE_LIMIT_EXCEEDED
  • Desencadenante: Un uso o deducción de crédito excedería el límite de sobreuso configurado
  • Mensaje: Límite de sobreuso excedido

​

Monedero

• INSUFFICIENT_WALLET_FUNDS
  • Desencadenante: Saldo del monedero < monto de débito
  • Mensaje: Fondos insuficientes en el monedero
• NEGATIVE_BALANCE_ADJUSTMENT
  • Desencadenante: Intento de hacer que el saldo del monedero sea negativo
  • Mensaje: No se permite que el saldo del monedero se vuelva negativo

​

Moneda, Impuestos & Región

• EXCHANGE_RATE_NOT_FOUND
  • Desencadenante: No hay tasa FX para el par de monedas from → to
  • Mensaje: No se encontró una tasa de cambio para convertir de Moneda a Moneda
• INVALID_TAX_ID
  • Desencadenante: Falló la validación de VAT/GST/TIN
  • Mensaje: El ID de Impuesto es inválido
• REQUEST_AMOUNT_BELOW_MINIMUM
  • Desencadenante: Monto < mínimo del producto
  • Mensaje: El monto no puede ser menor que el monto mínimo especificado para el producto
• TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
  • Desencadenante: Total combinado del carrito < mínimo del gateway
  • Mensaje: Se requiere un monto mínimo de para procesar el pago
• UNSUPPORTED_BILLING_CURRENCY
  • Desencadenante: Suscripciones restringidas a USD
  • Mensaje: La moneda de facturación que no sea USD no es compatible para suscripciones
• UNSUPPORTED_COUNTRY
  • Desencadenante: Geo aún no soportado
  • Mensaje: El país actualmente no es soportado
• UNSUPPORTED_CURRENCY
  • Desencadenante: Moneda del producto o complemento inválida
  • Mensaje: La moneda actualmente no es soportada / Sólo se soportan productos USD e INR actualmente / Sólo USD e INR soportados para el precio del complemento / Solo se puede solicitar USD o INR para la moneda_de_pago / Moneda No Soportada / Moneda inesperada para suscripciones con tarjeta India
• UNSUPPORTED_TAX_CATEGORY
  • Desencadenante: La cadena de categoría de impuestos no está en el enum
  • Mensaje: La categoría actualmente no es soportada

​

Validación & Solicitudes

• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • Desencadenante: El mismo item_id aparece dos veces en items[]
  • Mensaje: IDs de ítems duplicados especificados en el arreglo de ítems
• INVALID_QUERY_PARAMS
  • Desencadenante: Parámetros de consulta mutuamente excluyentes / mal formados
  • Mensaje: Los parámetros de consulta deben contener solo time_frame o (inicio, fin)
• INVALID_REQUEST_BODY
  • Desencadenante: JSON mal formado o violación del esquema
  • Mensaje: Su cuerpo de solicitud es inválido. Por favor, revise sus cabeceras de solicitud y objeto.
• INVALID_REQUEST_PARAMETERS
  • Desencadenante: Semántica incorrecta (e.g., fecha en el pasado)
  • Mensaje: No se puede cambiar next_billing_date a un tiempo pasado
• MAXIMUM_KEYS_REACHED
  • Desencadenante: Metadata / campos personalizados excedieron 50 pares
  • Mensaje: Excede 50 pares clave-valor

​

General & Sistema

• INTEGER_CONVERSION_FAILURE
  • Desencadenante: Cualquier conversión entera ↔ string/decimal que falla en el lado del servidor
  • Mensaje: Falla de Conversión Entera
• INTERNAL_SERVER_ERROR
  • Desencadenante: Excepciones no capturadas; debe registrar los detalles en el lado del servidor
  • Mensaje: Sin mensaje público (500 genérico)
• NOT_FOUND
  • Desencadenante: 404 genérico para cualquier recurso faltante
  • Mensaje: Ítem no encontrado (o más específico)
• TOO_MANY_REQUESTS
  • Desencadenante: Límite de tasa 429
  • Mensaje: Sin mensajes
• UNSUPPORTED_ACTION
  • Desencadenante: Acción no soportada para el tipo de recurso
  • Mensaje: Cambiar planes para suscripciones basadas en uso no es soportado

​

Mejores Prácticas

1. Maneje siempre los errores con elegancia en su aplicación
2. Implemente un registro de errores adecuado
3. Utilice mensajes de error apropiados para los usuarios finales
4. Implemente lógica de reintentos para errores transitorios
5. Contacte al soporte para problemas no resueltos

​

Soporte