Skip to main content

​
Descripción General

Cuando una solicitud falla, la API de Dodo Payments devuelve un código de estado HTTP y un cuerpo JSON que indica el error. Usa esta página para averiguar qué causó un error y cómo resolverlo. Cada respuesta de error incluye:
  • Un código de estado HTTP que indica la categoría general del error.
  • Un code que identifica el error exacto, por ejemplo UNSUPPORTED_COUNTRY.
  • Un message que explica el error en lenguaje sencillo. El message puede ser null, por ejemplo, para errores internos del servidor.
Basa el manejo de errores en code, no en message. Varios códigos devuelven más de un mensaje, según la causa. Usa estos códigos de error para:
  • Depurar problemas de integración.
  • Gestionar correctamente los errores en tu aplicación.
  • Mostrar comentarios útiles a tus clientes.
  • Mantener fiable el procesamiento de pagos.
Estos son errores de API y lógica empresarial. Para consultar los motivos de rechazo de tarjeta devueltos en un pago fallido (como INSUFFICIENT_FUNDS o CARD_DECLINED), consulta la referencia de Fallos de transacciones.

​
Códigos de error estándar de la API

La API utiliza estos códigos de estado HTTP para los errores:

​
Formato de la respuesta de error

El cuerpo de una respuesta de error contiene dos campos, code y message:

​
Referencia de códigos de error

Los códigos de error siguientes están agrupados por el área de la API con la que se relacionan. Cada entrada indica la condición que activa el error y el mensaje que devuelve la API. Los marcadores de posición, como {id}, representan valores que la API completa.

​
Autenticación y cuenta

  • UNAUTHORIZED
    • Activador: La solicitud no tiene una API key o esta no es válida (HTTP 401), o la API key no tiene el rol requerido por la acción (HTTP 403)
    • Mensaje: No tienes autorización para realizar esta acción
  • MERCHANT_NOT_LIVE
    • Activador: Una solicitud en modo live para una empresa que no tiene habilitados los pagos live (HTTP 403). Esto incluye una empresa que solo ha utilizado el modo test y una empresa cuyos pagos live aún no están habilitados porque la verificación no se ha completado. Las solicitudes en modo test no se ven afectadas.
    • Mensaje: Los pagos live no están habilitados para el merchant
  • BUSINESS_ARCHIVED
    • Activador: Cualquier solicitud dirigida al cliente para una empresa archivada (HTTP 403). Esto incluye checkout, enlaces de pago, la tienda, el Customer Portal y la activación de claves de licencia.
    • Mensaje: Esta empresa está archivada y ya no acepta solicitudes

​
Pagos y checkout

  • CHECKOUT_SESSION_CONSUMED
    • Activador: La sesión de checkout ya generó un pago (HTTP 403). Crea una nueva sesión de checkout.
    • Mensaje: Ya se ha generado un pago con la sesión de checkout indicada.
  • MANUAL_RETRY_ALREADY_PAID
    • Activador: Reintento manual de una factura de renovación cuyo pago ya se realizó correctamente. Enviarlo de nuevo cobraría dos veces al cliente.
    • Mensaje: El pago de esta factura ya se realizó correctamente
  • MANUAL_RETRY_HARD_DECLINE
    • Activador: Un reintento manual cuando el último fallo de la factura es un rechazo definitivo o no tiene un código de error clasificado. Otro cargo en la misma tarjeta no puede realizarse correctamente, así que actualiza el método de pago.
    • Mensaje: El último fallo de esta factura es un rechazo definitivo, por lo que el reintento no puede realizarse correctamente (o) El último fallo de esta factura no se puede clasificar, por lo que no se puede reintentar
  • MANUAL_RETRY_IN_FLIGHT
    • Activador: Un reintento manual mientras un pago de la factura está processing o aún no tiene un estado registrado. Espera el resultado de ese pago en lugar de enviarlo de nuevo.
    • Mensaje: Un pago de esta factura aún está en curso
  • MANUAL_RETRY_LIMIT_REACHED
    • Activador: Un reintento manual después de agotar los 3 envíos de la factura o antes de que haya transcurrido el tiempo de espera (HTTP 429). El segundo envío espera 1 hora después del primero y el tercero espera 3 horas después del segundo. El cuerpo solo contiene code y message. Para saber cuándo se permite el siguiente envío, lee retry_available_at de GET /payments/{payment_id}/retry.
    • Mensaje: Se han agotado todos los reintentos manuales de esta factura (o) La opción de reintentar ahora aún no está disponible para esta factura
  • NO_ELIGIBLE_PAYMENT_METHODS
    • Activador: No queda ningún método de pago disponible después del filtrado (HTTP 422)
    • Mensaje: No se encontraron métodos de pago aptos
  • PAYMENT_NOT_PERMITTED
    • Activador: Un checkout o intento de pago de un cliente incluido en la blocklist del merchant (HTTP 403). El código y el mensaje no indican deliberadamente ninguna causa.
    • Mensaje: Este pago no se puede procesar.
  • PAYMENT_NOT_RETRYABLE
    • Activador: Un reintento manual de un pago que no admite reintentos manuales. El pago no tiene factura, su factura no es una renovación de suscripción abierta, ningún pago de la factura ha fallado todavía, la suscripción no tiene configurada la facturación recurrente (por ejemplo, una suscripción bajo demanda) o el cliente está en la blocklist.
    • Mensaje: Varía según el motivo, por ejemplo: Solo se pueden reintentar los pagos de renovación de suscripciones
  • PAYMENT_NOT_SUCCEEDED
    • Activador: Un intento de reembolsar o procesar un pago que no se ha realizado correctamente
    • Mensaje: El pago proporcionado no se ha realizado correctamente
  • PREVIOUS_PAYMENT_PENDING
    • Activador: Un intento de crear un cargo mientras el pago anterior está en un estado no terminal. También se devuelve para un reintento manual cuando el pago más reciente de la factura no es failed ni está en curso, por ejemplo, requires_customer_action o cancelled.
    • Mensaje: No se puede crear un nuevo cargo porque el pago anterior aún no se ha realizado correctamente (o) El pago más reciente de esta factura no ha fallado
  • UNSUCCESSFUL_PAYMENT_ID
    • Activador: El ID de pago hace referencia a un pago que no se ha realizado correctamente
    • Mensaje: El ID de pago tiene un estado fallido.

​
Connectors y BYOP

Estos errores se relacionan con connectors de pago propiedad del merchant (Bring Your Own Processor, o BYOP).
  • BYOP_CONNECTOR_DISABLED
    • Activador: Se actualiza el método de pago de una suscripción enviada a través de un connector BYOP deshabilitado. Dodo Payments no recurre a sus propios connectors, así que vuelve a habilitar primero el connector.
    • Mensaje: La suscripción se envía a través del connector propio del merchant (BYOP), que está deshabilitado actualmente
  • BYOP_CUSTOM_INVOICE_ADDRESS_MISSING
    • Activador: Un pago enviado a través del connector del merchant (BYOP) no tiene una dirección de factura personalizada
    • Mensaje: Se requiere una dirección de factura personalizada de BYOP cuando el pago se envía a través del connector del merchant
  • CONNECTOR_LABEL_ALREADY_EXISTS
    • Activador: Se crea un connector con una etiqueta que ya existe
    • Mensaje: Ya existe un connector con esta etiqueta. Elige otra etiqueta.

​
Reembolsos

  • EXISTING_REFUND_REQUEST_PROCESSING
    • Activador: Una solicitud de reembolso anterior aún se está procesando
    • Mensaje: Aún se está procesando una solicitud de reembolso con el estado “Pending”
  • LINE_ITEM_FULLY_REFUNDED
    • Activador: Se intenta reembolsar un line item que ya se ha reembolsado por completo
    • Mensaje: El line item {id} se ha reembolsado por completo y no se puede reembolsar más.
  • LINE_ITEM_NOT_FOUND
    • Activador: El ID del elemento no forma parte del pago indicado
    • Mensaje: No se encontró el line item {id} en el pago
  • LINE_ITEM_PRORATED
    • Activador: Se intenta reembolsar o actualizar un line item prorrateado
    • Mensaje: El line item {id} no se puede reembolsar porque está prorrateado
  • LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
    • Activador: El importe del reembolso, incluidos los impuestos, es superior al importe pagado
    • Mensaje: El importe de reembolso solicitado para el line item {id}, incluidos los impuestos, es {amount}, que supera el importe pagado {amount}
  • LINE_ITEM_REFUND_AMOUNT_TOO_LOW
    • Activador: El importe del reembolso es inferior al umbral mínimo
    • Mensaje: El importe de reembolso solicitado para el line item {id} es {amount}, que es demasiado bajo
  • NOTHING_TO_REFUND
    • Activador: No queda ningún importe reembolsable porque todos los line items positivos ya se han reembolsado por completo
    • Mensaje: No queda ningún importe reembolsable. Todos los line items positivos se han reembolsado por completo.
  • PARTIAL_REFUND_NOT_ALLOWED
    • Activador: Se intenta realizar un reembolso parcial con un método de pago que solo admite reembolsos completos
    • Mensaje: Este método de pago no permite reembolsos parciales
  • PAYMENT_ALREADY_REFUNDED
    • Activador: Un reembolso duplicado
    • Mensaje: Este pago ya se ha reembolsado
  • PAYMENT_HAS_BEEN_REFUNDED
    • Activador: El pago se ha reembolsado por completo
    • Mensaje: El ID de pago se ha reembolsado por completo.
  • REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT
    • Activador: El importe total del reembolso es superior al importe pagado
    • Mensaje: El importe de reembolso calculado es superior al importe pagado
  • REFUND_WINDOW_EXPIRED
    • Activador: El reembolso se solicita fuera del plazo permitido
    • Mensaje: No se pueden iniciar reembolsos {days} días después de crear el pago. Contacta con support@dodopayments.com.
  • ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
    • Activador: Se intenta reembolsar un pago de importe cero
    • Mensaje: No se puede reembolsar un pago con un importe monetario cero

​
Suscripciones y add-ons

  • ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
    • Activador: Se intenta añadir add-ons a una suscripción con facturación basada en el uso
    • Mensaje: Las suscripciones no admiten add-ons para la facturación basada en el uso
  • ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
    • Activador: Se intenta añadir add-ons a una suscripción bajo demanda
    • Mensaje: No se permiten add-ons para suscripciones bajo demanda
  • CANCEL_SCHEDULED_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
    • Activador: Customer Portal intenta cancelar un cambio de plan programado mientras la empresa ha deshabilitado esa acción
    • Mensaje: El Customer Portal tiene deshabilitada la cancelación de cambios de plan programados.
  • CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
    • Activador: Se intenta cobrar una suscripción programada para cancelarse
    • Mensaje: Suscripción programada para cancelarse
  • CUSTOMER_HAS_EXISTING_SUBSCRIPTION
    • Activador: Se crea una suscripción para un cliente que ya tiene una, cuando la empresa no permite varias suscripciones por cliente
    • Mensaje: El cliente {id} ya tiene una suscripción. Para permitir varias suscripciones por cliente, cambia la configuración de la empresa
  • DO_NOT_BILL_NOT_ALLOWED_IN_CUSTOMER_PORTAL
    • Activador: Se utiliza el modo de prorrateo do_not_bill en un cambio de plan del Customer Portal
    • Mensaje: El modo de prorrateo do_not_bill no está permitido en el Customer Portal
  • DUPLICATE_ADDON_IDS_IN_REQUEST
    • Activador: El mismo addon_id aparece más de una vez en la solicitud
    • Mensaje: No se permiten IDs de add-ons duplicados
  • INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
    • Activador: Un cambio de plan en una suscripción inactiva
    • Mensaje: No se admiten cambios de plan para suscripciones inactivas
  • INVALID_PRORATION_MODE_WITH_NEXT_BILLING_DATE
    • Activador: Se utiliza un modo de prorrateo distinto de full_immediately con effective_at: next_billing_date
    • Mensaje: Con effective_at: next_billing_date solo se permite el modo de prorrateo full_immediately
  • MISSING_ADDON_IDS
    • Activador: La lista addon_id está vacía o contiene IDs desconocidos
    • Mensaje: Uno o más IDs de producto no existen: {id}
  • ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
    • Activador: Un cambio de plan en una suscripción bajo demanda
    • Mensaje: No se admiten cambios de plan para suscripciones bajo demanda
  • ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
    • Activador: Se intenta usar una suscripción bajo demanda con facturación basada en el uso
    • Mensaje: Las suscripciones bajo demanda no se admiten para la facturación basada en el uso
  • ONE_TIME_PRODUCTS_NOT_ALLOWED_FOR_ON_DEMAND
    • Activador: Se añade un producto único a una suscripción bajo demanda
    • Mensaje: No se permiten productos únicos en suscripciones bajo demanda
  • PENDING_PLAN_CHANGE_EXISTS
    • Trigger: Se solicita un cambio de plan nuevo mientras uno anterior aún está pendiente de pago. Para reemplazar un cambio pendiente mediante un enlace de pago, establece cancel_older_payment_link: true.
    • Message: Ya existe un cambio de plan pendiente para esta suscripción. Espera a que se complete el pago actual.
  • PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
    • Activador: Un cambio de plan mediante Customer Portal mientras la empresa lo ha deshabilitado
    • Mensaje: El cambio de plan de suscripción mediante Customer Portal está deshabilitado.
  • PLAN_CHANGE_LINK_CANCEL_FAILED
    • Trigger: Un cambio de plan con cancel_older_payment_link: true no pudo cancelar el enlace de pago anterior. No se modificó nada, por lo que puedes volver a intentar la solicitud.
    • Message: No se pudo cancelar el enlace de pago anterior. Inténtalo de nuevo.
  • PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
    • Trigger: Un cambio de plan en una suscripción programada para cancelarse
    • Message: Suscripción programada para cancelarse
  • PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED
    • Trigger: Un cambio de plan con cancel_older_payment_link: true mientras el cliente ya ha pagado el cambio de plan anterior. Ese cambio se aplica, así que no vuelvas a intentarlo.
    • Message: El cliente ya pagó el cambio de plan anterior. Se aplicará en breve.
  • PLAN_CHANGE_PAYMENT_IN_PROGRESS
    • Trigger: Un cambio de plan con cancel_older_payment_link: true mientras el cliente está pagando el cambio de plan anterior, por ejemplo, durante 3D Secure. Vuelve a intentarlo cuando el pago se complete o falle.
    • Message: El cliente está pagando el cambio de plan anterior. Inténtalo de nuevo más tarde.
  • SCHEDULE_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
    • Trigger: Programar un cambio de plan mediante el Customer Portal cuando la empresa lo ha desactivado
    • Message: La programación de cambios de plan está desactivada para esta empresa.
  • SCHEDULED_PLAN_CHANGE_EXISTS
    • Trigger: Crear un cambio de plan programado cuando ya existe uno
    • Message: Ya existe un cambio de plan programado para esta suscripción. Cancela el cambio programado existente antes de crear uno nuevo.
  • SCHEDULED_PLAN_CHANGE_NOT_FOUND
    • Trigger: Hacer referencia a un cambio de plan programado que no existe o cancelarlo
    • Message: No se encontró ningún cambio de plan programado para esta suscripción.
  • SUBSCRIPTION_EXPIRED
    • Trigger: Cobrar una suscripción después de su fecha expires_at
    • Message: La suscripción expiró; no se pueden crear nuevos cargos
  • SUBSCRIPTION_HAS_NO_PAYMENT_METHOD
    • Trigger: Reintento manual de una suscripción que no tiene un método de pago guardado para cobrar fuera de sesión
    • Message: Esta suscripción no tiene un método de pago guardado para realizar el cargo
  • SUBSCRIPTION_INACTIVE
    • Trigger: El estado de la suscripción no es active
    • Message: La suscripción no está activa (or) Esta suscripción no está activa, por lo que no se puede programar una cancelación
  • SUBSCRIPTION_NOT_ON_DEMAND
    • Trigger: Una acción bajo demanda en una suscripción que se factura en un intervalo fijo
    • Message: La suscripción ya no es bajo demanda
  • SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
    • Trigger: Los reintentos de pago de la suscripción superaron el número máximo de intentos
    • Message: Se superó el límite máximo de 10 intentos de reintento para esta suscripción

​
Clientes y lista de bloqueo

  • CUSTOMER_ALREADY_BLOCKED
    • Trigger: Bloquear a un cliente que ya está en la lista de bloqueo y no tiene suscripciones activas restantes que cancelar (HTTP 409)
    • Message: Este cliente ya está en la lista de bloqueo
  • PORTAL_ACTION_NOT_PERMITTED
    • Trigger: Un cliente bloqueado llama a una ruta de escritura del Customer Portal: cancelar, pausar, reanudar, cambiar el plan o actualizar el método de pago (HTTP 403). Las rutas de lectura permanecen abiertas. El código y el mensaje no indican deliberadamente ninguna causa.
    • Message: Esta acción no está disponible.

​
Productos, carrito y marcas

  • BRAND_ALREADY_ARCHIVED
    • Trigger: Archivar una marca que ya está archivada
    • Message: La marca ya está archivada
  • BRAND_ARCHIVED
    • Trigger: Actualizar una marca archivada, enviarla para verificación o asociarle un producto, una colección de productos o una suscripción nuevos
    • Message: La marca está archivada (or) La marca está archivada y no se puede actualizar (or) La marca está archivada y no se puede enviar para verificación
  • BRAND_ARCHIVE_TARGET_REQUIRED
    • Trigger: Archivar una marca que todavía contiene productos, suscripciones activas o colecciones de productos sin un destino move_products_to
    • Message: La marca tiene {count} producto(s). Establece move_products_to en una marca de destino para volver a asociarlos. El mensaje menciona las suscripciones activas o las colecciones de productos cuando estas impiden el archivado.
  • BRAND_MISMATCH
    • Trigger: Los artículos del carrito pertenecen a marcas diferentes
    • Message: Todos los artículos del carrito de productos deben pertenecer a la misma marca
  • BRAND_NOT_ENABLED
    • Trigger: La marca está desactivada o no está activa
    • Message: La marca proporcionada no está habilitada
  • BRAND_SUBMISSION_NOT_ENABLED
    • Trigger: La función de reenvío de la verificación de marca no está habilitada
    • Message: Brand verificatin resubmission is not enabled (escrito exactamente como lo devuelve la API)
  • CANNOT_ARCHIVE_PRIMARY_BRAND
    • Trigger: Archivar la marca principal, cuyo ID de marca es el ID de la empresa
    • Message: La marca principal no se puede archivar
  • FILE_IN_USE
    • Trigger: Eliminar un archivo de producto digital al que todavía hacen referencia concesiones activas
    • Message: El archivo digital está referenciado por concesiones activas
  • INVALID_BRAND_ARCHIVE_TARGET
    • Trigger: move_products_to especifica la marca que se está archivando, una marca archivada o una marca de otra empresa
    • Message: move_products_to debe ser una marca de esta empresa que no esté archivada (or) move_products_to no puede ser la marca que archivas
  • INVALID_SUGGESTED_PRICE
    • Trigger: Un precio sugerido de Pay What You Want es inferior al precio mínimo
    • Message: Suggested Price no puede ser inferior al precio mínimo. En el caso de Pay What You Want, el precio se considera el importe mínimo aceptado
  • LOCALIZED_PRICE_ALREADY_EXISTS
    • Trigger: Ya existe un precio localizado para este producto y país o moneda
    • Message: Ya existe un precio localizado para este producto y país/moneda
  • LOCALIZED_PRICE_DUPLICATES_BASE
    • Trigger: El precio localizado duplica la moneda o el país base del producto
    • Message: El precio localizado duplica la moneda/el país base del producto
  • LOCALIZED_PRICE_SHAPE_MISMATCH
    • Trigger: La estructura del precio localizado no coincide con pricing_mode del producto
    • Message: La estructura del precio localizado no coincide con pricing_mode del producto
  • MISSING_PRODUCT_INFORMATION
    • Trigger: El producto existe, pero falta información obligatoria
    • Message: El producto {id} existe, pero falta otra información obligatoria o esta no es válida
  • PAY_AS_YOU_WANT_AMOUNT_REQUIRED
    • Trigger: Falta el importe para un producto Pay What You Want
    • Message: El importe es obligatorio para un producto Pay What You Want
  • PRODUCT_CART_EMTPY
    • Trigger: Se envía un carrito de productos vacío
    • Message: product_cart está vacío (el código de error se escribe intencionadamente como EMTPY para coincidir con el valor exacto que devuelve la API)
  • PRODUCT_COLLECTION_IS_DELETED
    • Trigger: Operar en una colección de productos que se ha eliminado
    • Message: Sin mensaje
  • PRODUCT_COLLECTION_MUST_HAVE_PRODUCTS
    • Trigger: Eliminar el último producto o el último grupo con productos de una colección
    • Message: No se puede eliminar el último producto de una colección. Archiva la colección en su lugar. (or) No se puede eliminar el último grupo con productos. Archiva la colección en su lugar.
  • PRODUCT_IS_DELETED
    • Trigger: El producto se ha eliminado
    • Message: Sin mensaje
  • PRODUCT_PRICING_MODE_REQUIRED
    • Trigger: Añadir precios localizados antes de establecer pricing_mode del producto
    • Message: Debe establecerse pricing_mode del producto antes de añadir precios localizados
  • SLUG_ALREADY_TAKEN
    • Trigger: El slug o la URL corta del producto solicitado ya está en uso
    • Message: El slug ya está ocupado
  • UNABLE_TO_EDIT_PRIMARY_BRAND
    • Trigger: Intentar actualizar la marca principal mediante la API de marcas habitual
    • Message: La marca principal no se puede actualizar mediante este endpoint de API.

​
Descuentos

  • DISCOUNT_ALREADY_USED_ON_SUBSCRIPTION
    • Trigger: Aplicar de nuevo un descuento que ya se ha utilizado en esta suscripción
    • Message: Este descuento ya se ha utilizado en esta suscripción
  • DISCOUNT_CODE_ALREADY_EXISTS
    • Trigger: Crear un código de descuento que ya existe
    • Message: El código de descuento ya existe
  • DISCOUNT_CODE_EXPIRED
    • Trigger: El código de descuento ha superado su fecha expires_at
    • Message: El código de descuento ha caducado
  • DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
    • Trigger: El código se utiliza después de alcanzar usage_limit
    • Message: El límite de uso no puede ser inferior a times_used (or) El código de descuento alcanzó el límite de uso
    • Note: Terminal. El código se agotó, así que no vuelvas a intentarlo.
  • DISCOUNT_CONCURRENT_REDEMPTION
    • Trigger: Otro canje del mismo código mantuvo el bloqueo del límite de uso durante demasiado tiempo (HTTP 503)
    • Message: El descuento se está canjeando simultáneamente; vuelve a intentarlo
    • Note: Transitorio. Es posible que el código aún tenga capacidad, por lo que es seguro volver a intentar la solicitud. No muestres esto al cliente como un código agotado.
  • DISCOUNT_CURRENCY_OPTION_INVALID
    • Trigger: currency_options no válido al crear o actualizar
    • Message: Un descuento fijo requiere al menos una opción de moneda con un valor predeterminado resoluble (or) No se permiten opciones de moneda duplicadas (or) Solo una opción de moneda puede marcarse como predeterminada
  • DISCOUNT_CUSTOMER_NOT_ELIGIBLE
    • Trigger: El cliente no cumple customer_eligibility del código (first_time, existing o no está en la lista de permitidos de un código specific)
    • Message: El cliente no puede utilizar este código de descuento
  • DISCOUNT_MINIMUM_SUBTOTAL_NOT_MET
    • Trigger: El subtotal del carrito es inferior a minimum_subtotal configurado para la moneda del checkout
    • Message: El subtotal del carrito es inferior al subtotal mínimo requerido por el descuento
  • DISCOUNT_NOT_YET_ACTIVE
    • Trigger: El código se utiliza antes de su fecha starts_at
    • Message: El código de descuento aún no está activo (starts_at está en el futuro)
  • DISCOUNT_PER_CUSTOMER_USAGE_LIMIT_EXCEEDED
    • Trigger: El cliente ya ha canjeado el código per_customer_usage_limit veces
    • Message: Se superó el límite de uso por cliente para este código de descuento
  • DISCOUNT_NOT_APPLICABLE_TO_NEW_PRODUCT
    • Trigger: Un cambio de plan a un producto al que no se aplica el descuento existente
    • Message: El descuento no se aplica al producto del nuevo plan
  • DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
    • Trigger: El código se aplica a una suscripción bajo demanda
    • Message: El cupón de descuento no está disponible para suscripciones bajo demanda
  • DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
    • Trigger: El código se aplica a productos que no cubre
    • Message: El cupón de descuento no está disponible para este producto
  • INVALID_DISCOUNT_CODE
    • Trigger: El código no existe o no se aplica a ningún producto del carrito
    • Message: Código de descuento no válido (or) El código de descuento no se puede aplicar a ningún producto del carrito
  • INVALID_PERCENTAGE
    • Trigger: El porcentaje es superior al 100 % (10.000 puntos básicos)
    • Message: El porcentaje no puede ser superior a 10000 (or) El importe del código de descuento no puede ser superior al 100 %
  • UNSUPPORTED_DISCOUNT_TYPE
    • Trigger: Un tipo de descuento que no es compatible. percentage y flat son compatibles; los descuentos por importe unitario no lo son.
    • Message: Solo se admiten códigos de descuento porcentuales y fijos (or) Por ahora, solo se admiten códigos de descuento porcentuales

​
Claves de licencia

  • ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT
    • Trigger: El nuevo límite de activación de una clave de licencia es inferior a su número actual de instancias
    • Message: El nuevo límite de activación no puede ser inferior al número actual de instancias
  • INACTIVE_LICENSE_KEY
    • Trigger: El estado de la clave de licencia no es active
    • Message: La clave de licencia no está activa
  • LICENSE_KEY_LIMIT_REACHED
    • Trigger: El número de activaciones alcanzó el límite de activación
    • Message: Se alcanzó el límite de activación de la clave de licencia
  • LICENSE_KEY_NOT_FOUND
    • Trigger: El ID de instancia o el ID de clave de licencia no es válido
    • Message: No se encontró la instancia de la clave de licencia o no pertenece a esta clave de licencia
  • NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
    • Trigger: Intentar establecer una fecha de caducidad en una clave de licencia basada en suscripción
    • Message: No se puede establecer una fecha de caducidad para una clave de licencia basada en suscripción

​
Facturación basada en el uso y medidores

  • DUPLICATE_METER_IDS_IN_REQUEST
    • Trigger: El mismo ID de medidor aparece más de una vez en la solicitud
    • Message: No se permiten IDs de medidor duplicados
  • INVALID_QUANTITY
    • Trigger: Una cantidad distinta de 1 para un producto con precios basados en el uso
    • Message: Solo se permite una cantidad de 1 en productos con precios basados en el uso
  • METER_IS_DELETED
    • Trigger: Intentar utilizar un medidor eliminado
    • Message: El medidor ya se ha eliminado
  • MISSING_METER_IDS
    • Trigger: La lista de IDs de medidores está vacía o contiene IDs no válidos
    • Message: Uno o más IDs de medidores no existen: {id}

​
Facturación basada en créditos

  • CREDIT_ENTITLEMENT_IS_DELETED
    • Trigger: Operar en un derecho de crédito que se ha eliminado
    • Message: El derecho de crédito ya se ha eliminado
  • CREDIT_ENTITLEMENT_NAME_ALREADY_EXISTS
    • Trigger: Crear un derecho de crédito con un nombre que ya existe
    • Message: Ya existe un derecho de crédito con este nombre
  • OVERAGE_LIMIT_EXCEEDED
    • Trigger: Un uso o una deducción de crédito superaría el límite de exceso configurado
    • Message: Se superó el límite de exceso

​
Cartera

  • INSUFFICIENT_WALLET_FUNDS
    • Trigger: El saldo de la cartera es inferior al importe del débito
    • Message: Fondos insuficientes en la cartera
  • NEGATIVE_BALANCE_ADJUSTMENT
    • Trigger: Intentar hacer negativo el saldo de la cartera
    • Message: No se permite que el saldo de la cartera sea negativo

​
Moneda, impuestos y región

  • EXCHANGE_RATE_NOT_FOUND
    • Trigger: No existe un tipo de cambio para el par de monedas
    • Message: No se encontró un tipo de cambio para convertir de {currency} a {currency}
  • INVALID_TAX_ID
    • Trigger: El VAT, GST o TIN no superó la validación
    • Message: El Tax Id no es válido
  • REQUEST_AMOUNT_BELOW_MINIMUM
    • Trigger: El importe es inferior al mínimo establecido para el producto
    • Message: El importe no puede ser inferior al importe mínimo especificado para el producto
  • TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
    • Trigger: El total combinado del carrito, incluidos los impuestos, es inferior al importe mínimo necesario para procesar un pago. El mínimo depende de la moneda de facturación y de si el pago es único o corresponde a una suscripción. Para monedas distintas de USD, EUR y GBP, el total también se compara con el mínimo en USD. Consulta Importes mínimos
    • Message: Se requiere un importe mínimo de {display_str} para procesar el pago, por ejemplo Minimum amount of 1.00 USD is required to process payment
  • UNSUPPORTED_BILLING_CURRENCY
    • Trigger: La moneda de facturación solicitada no es compatible con esta suscripción
    • Message: Las suscripciones no admiten monedas de facturación distintas de USD
  • UNSUPPORTED_COUNTRY
    • Trigger: El país no es compatible
    • Message: El país {country_name} no es compatible actualmente
  • UNSUPPORTED_CURRENCY
    • Trigger: La moneda del producto o complemento no es una moneda en la que Dodo Payments pueda realizar cargos. Los precios base se pueden establecer en cualquier moneda admitida para cargos, por lo que este error normalmente significa que el código de moneda no es válido o no es compatible.
    • Message: La moneda no es compatible actualmente (or) Actualmente solo se admiten productos en USD e INR (or) Actualmente solo se admite USD e INR para el precio del complemento (or) Solo se puede solicitar USD o INR para billing_currency (or) Moneda no compatible (or) Moneda inesperada para suscripciones con tarjetas indias
  • UNSUPPORTED_TAX_CATEGORY
    • Trigger: La categoría fiscal no es uno de los valores compatibles
    • Message: La categoría {category} no es compatible actualmente

​
Validación y solicitudes

  • DUPLICATE_LINE_ITEMS_IN_REQUEST
    • Trigger: El mismo item_id aparece más de una vez en items[]
    • Message: Se especificaron item_ids duplicados en la matriz items
  • INVALID_QUERY_PARAMS
    • Trigger: Parámetros de consulta que son mutuamente excluyentes o tienen un formato incorrecto
    • Message: Los parámetros de consulta solo deben contener time_frame o (start, end) (or) El inicio del intervalo no puede ser posterior al final
  • INVALID_REQUEST_BODY
    • Trigger: JSON con formato incorrecto o incumplimiento del esquema
    • Message: El cuerpo de la solicitud no es válido. Comprueba los encabezados y el objeto de la solicitud.
  • INVALID_REQUEST_PARAMETERS
    • Trigger: Valores de parámetros que son válidos en cuanto al formato, pero no en cuanto al significado, por ejemplo, una fecha pasada
    • Message: No se puede cambiar next_billing_date a una fecha pasada (or) Un checkout con más de un producto de suscripción no puede contener productos de un solo pago (or) Todos los IDs de producto deben ser únicos (or) Las suscripciones bajo demanda no pueden contener más de un producto (or) Un checkout puede contener como máximo 20 productos de suscripción (or) No se permiten productos de suscripción duplicados en un checkout
  • MAXIMUM_KEYS_REACHED
    • Trigger: Los metadatos o campos personalizados superan los 50 pares clave-valor
    • Message: Se superan los 50 pares clave-valor

​
General y sistema

  • INTEGER_CONVERSION_FAILURE
    • Trigger: Falla una conversión del lado del servidor entre un entero y una cadena o decimal, por ejemplo, cuando el total del carrito es demasiado grande para procesarlo
    • Message: Error de conversión de enteros (or) El total del carrito es demasiado grande para procesarlo. Reduce la cantidad o selecciona otra moneda de facturación.
  • INTERNAL_SERVER_ERROR
    • Trigger: Un error inesperado del servidor. Registra los detalles de la solicitud en tu sistema.
    • Message: Sin mensaje público (500 genérico; message normalmente es null)
  • NOT_FOUND
    • Trigger: 404 genérico para cualquier recurso que falte
    • Message: No se encontró el elemento (or un mensaje más específico que indique qué falta)
  • TOO_MANY_REQUESTS
    • Trigger: Se superó un límite de frecuencia (HTTP 429)
    • Message: Sin mensaje
  • UNSUPPORTED_ACTION
    • Trigger: Una acción que el tipo de recurso no admite
    • Message: No se admite cambiar de plan para suscripciones basadas en el uso

​
Prácticas recomendadas

Sigue estas prácticas al gestionar errores de la API:
  1. Gestiona todas las respuestas de error en tu aplicación y ramifica según code en lugar de message.
  2. Registra el estado HTTP, code y message de cada solicitud fallida.
  3. Muestra a los usuarios finales un mensaje redactado para ellos en lugar del message sin procesar de la API.
  4. Reintenta únicamente los errores transitorios, como las respuestas 429 y 5xx o DISCOUNT_CONCURRENT_REDEMPTION, después de un intervalo.
  5. Contacta con soporte para los errores que no puedas resolver.

​
Soporte

Para obtener más ayuda con los códigos de error o los problemas de integración, contacta con el equipo de soporte en support@dodopayments.com.
Última modificación el 8 de octubre de 2026