错误代码

​

概述

• 指示错误一般类别的 HTTP 状态代码
• 识别错误确切性质的特定错误代码
• 解释出错原因的人类可读错误消息
• 适用时关于错误的附加详细信息

• 调试集成问题
• 在您的应用程序中实现适当的错误处理
• 向最终用户提供有意义的反馈
• 维护强大的支付处理系统

​

标准 API 错误代码

​

错误响应格式

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

​

错误代码参考

• ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT
  • 触发条件： 许可密钥激活：新限制 < 现有实例数量
  • 消息： 新激活限制不能低于当前实例数量
• ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
  • 触发条件： 尝试将插件添加到基于用量的计费订阅
  • 消息： 基于用量计费的订阅不支持插件
• ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
  • 触发条件： 尝试将插件添加到按需订阅
  • 消息： 按需订阅不允许插件
• BRAND_MISMATCH
  • 触发条件： 购物车中的商品属于不同品牌
  • 消息： 产品购物车中的所有商品应属于同一品牌
• BRAND_NOT_ENABLED
  • 触发条件： 品牌被禁用或未激活
  • 消息： 所提供的品牌未启用
• BRAND_SUBMISSION_NOT_ENABLED
  • 触发条件： 品牌验证重新提交功能未启用
  • 消息： 品牌验证重新提交未启用
• CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • 触发条件： 尝试向计划取消的订阅收费
  • 消息： 订阅已计划取消
• CHECKOUT_SESSION_CONSUMED
  • 触发条件： 结账会话已生成支付
  • 消息： 结账会话已被使用
• DISCOUNT_CODE_ALREADY_EXISTS
  • 触发条件： 重复创建折扣码
  • 消息： 折扣码已存在
• DISCOUNT_CODE_EXPIRED
  • 触发条件： 折扣码已过 expires_at 日期
  • 消息： 折扣码已过期
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • 触发条件： 在 usage_limit 达到后再次使用折扣
  • 消息： 使用限制不能少于 times_used / 折扣码已达到使用限制
• DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
  • 触发条件： 将代码应用于按需订阅
  • 消息： 折扣券不适用于按需订阅
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • 触发条件： 将代码应用于无关产品
  • 消息： 该产品不支持折扣券
• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • 触发条件： 同一 item_id 在 items[] 中出现两次
  • 消息： items 数组中指定了重复的 item_ids
• DUPLICATE_METER_IDS_IN_REQUEST
  • 触发条件： 相同的计量器 ID 在请求中出现多次
  • 消息： 不允许重复的计量器 ID
• EXCHANGE_RATE_NOT_FOUND
  • 触发条件： from → to 货币对暂无外汇汇率
  • 消息： 找不到从 Currency 转换到 Currency 的汇率
• EXISTING_REFUND_REQUEST_PROCESSING
  • 触发条件： 之前的退款请求仍在处理
  • 消息： 状态为“Pending”的退款请求仍在处理中
• INACTIVE_LICENSE_KEY
  • 触发条件： 密钥状态不等于 ACTIVE
  • 消息： 许可密钥未激活
• INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
  • 触发条件： 在非活跃订阅上更改计划
  • 消息： 非活跃订阅不支持更改计划
• INSUFFICIENT_WALLET_FUNDS
  • 触发条件： 钱包余额小于借记金额
  • 消息： 钱包余额不足
• INTEGER_CONVERSION_FAILURE
  • 触发条件： 服务器端的任意整数与字符串/十进制转换失败
  • 消息： 整数转换失败
• INTERNAL_SERVER_ERROR
  • 触发条件： 未捕获的异常；应在服务器端记录详细信息
  • 消息： 无公开消息（通用 500）
• INVALID_DISCOUNT_CODE
  • 触发条件： 代码不存在 / 不适用
  • 消息： 无效折扣码 / 折扣码无法应用于购物车中的任何产品
• INVALID_PERCENTAGE
  • 触发条件： 百分比金额 > 100%（或 10,000 个基点）
  • 消息： 百分比金额不能超过 10000 / 折扣码金额不能超过 100%
• INVALID_QUANTITY
  • 触发条件： 为基于用量定价指定了无效数量
  • 消息： 基于用量价格的产品仅允许数量为 1
• INVALID_QUERY_PARAMS
  • 触发条件： 互斥或格式错误的查询参数
  • 消息： 查询参数应仅包含 time_frame 或 (start, end)
• INVALID_REQUEST_BODY
  • 触发条件： JSON 格式错误或架构违规
  • 消息： 您的请求体无效。请检查请求头和对象。
• INVALID_REQUEST_PARAMETERS
  • 触发条件： 语义错误（例如日期在过去）
  • 消息： 无法将 next_billing_date 更改为过去时间
• INVALID_SUGGESTED_PRICE
  • 触发条件： PWYW 价格低于允许的最低价格
  • 消息： 建议价格不能低于最低价格。在 pay what you want 的情况下，价格被视为最低可接受金额
• INVALID_TAX_ID
  • 触发条件： VAT/GST/TIN 验证失败
  • 消息： 税号无效
• LICENSE_KEY_LIMIT_REACHED
  • 触发条件： 激活次数等于限制
  • 消息： 许可密钥激活限制已达
• LICENSE_KEY_NOT_FOUND
  • 触发条件： 实例 ID 或密钥 ID 无效
  • 消息： 未找到许可密钥实例或其不属于此许可密钥
• LINE_ITEM_FULLY_REFUNDED
  • 触发条件： 尝试退款已全额退款的行项目
  • 消息： 行项目 已全部退款，无法再次退款。
• LINE_ITEM_NOT_FOUND
  • 触发条件： 项目 ID 不属于引用的支付
  • 消息： 在支付中未找到行项目
• LINE_ITEM_PRORATED
  • 触发条件： 对按比例分配的行项目尝试退款或更新
  • 消息： 行项目 无法退款，因为它是按比例分配的
• LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
  • 触发条件： 退款金额大于已支付金额（含税）
  • 消息： 行项目 请求的退款金额（含税）为 ，高于已支付金额
• LINE_ITEM_REFUND_AMOUNT_TOO_LOW
  • 触发条件： 退款金额低于最低阈值
  • 消息： 行项目 请求的退款金额为 ，过低
• MAXIMUM_KEYS_REACHED
  • 触发条件： 元数据/自定义字段超过 50 对
  • 消息： 超过 50 个键值对
• MERCHANT_NOT_LIVE
  • 触发条件： 业务仍处于测试/沙箱模式
  • 消息： 商家尚未上线
• METER_IS_DELETED
  • 触发条件： 试图使用已删除的计量器
  • 消息： 该计量器已被删除
• MISSING_ADDON_IDS
  • 触发条件： addon_id 列表为空或包含未知 ID
  • 消息： 一个或多个产品 ID 不存在：
• MISSING_METER_IDS
  • 触发条件： 计量器 ID 列表为空或包含无效 ID
  • 消息： 一个或多个计量器 ID 不存在：
• MISSING_PRODUCT_INFORMATION
  • 触发条件： 产品存在但缺少必需信息
  • 消息： 产品 存在，但其他必填信息缺失或无效
• NEGATIVE_BALANCE_ADJUSTMENT
  • 触发条件： 尝试使钱包余额为负
  • 消息： 不允许将钱包余额设为负数
• NO_ELIGIBLE_PAYMENT_METHODS
  • 触发条件： 过滤后无剩余项目
  • 消息： 未找到符合条件的支付方式
• NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
  • 触发条件： 尝试为基于订阅的密钥设置到期日期
  • 消息： 无法为基于订阅的许可密钥设置到期日期
• NOT_FOUND
  • 触发条件： 缺失资源的通用 404
  • 消息： 项目未找到 (或更具体的)
• ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
  • 触发条件： 按需服务不允许更换计划
  • 消息： 按需订阅不支持更改计划
• ON_DEMAND_SUBSCRIPTIONS_NOT_ENABLED
  • 触发条件： 企业的功能开关关闭
  • 消息： 此企业未启用按需订阅
• ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
  • 触发条件： 试图在基于用量计费中使用按需订阅
  • 消息： 基于用量计费不支持按需订阅
• PAY_AS_YOU_WANT_AMOUNT_REQUIRED
  • 触发条件： PWYW 产品缺少价格
  • 消息： pay as you want 产品必须填写金额
• PAYMENT_ALREADY_REFUNDED
  • 触发条件： 重复退款
  • 消息： 此支付已被退款
• PAYMENT_HAS_BEEN_REFUNDED
  • 触发条件： 该支付已全额退款
  • 消息： 该支付 ID 已全额退款。
• PAYMENT_NOT_SUCCEEDED
  • 触发条件： 尝试退款/处理未成功的支付
  • 消息： 所提供的支付未成功
• PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • 触发条件： 在计划取消的订阅上尝试更改计划
  • 消息： 订阅已计划取消
• PREVIOUS_PAYMENT_PENDING
  • 触发条件： 尝试在先前支付处于非终止状态时创建费用
  • 消息： 无法创建新费用，因为之前的支付尚未成功
• PRODUCT_CART_EMPTY
  • 触发条件： 提交了空的产品购物车
  • 消息： product_cart 为空
• PRODUCT_IS_DELETED
  • 触发条件： 产品已软删除
  • 消息： 无消息
• REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT
  • 触发条件： 汇总退款金额大于已支付金额
  • 消息： 计算得出的退款金额大于已支付金额
• REFUND_WINDOW_EXPIRED
  • 触发条件： 超出允许的退款窗口
  • 消息： 付款创建 天后无法发起退款。请联系 support@dodopayments.com。
• REQUEST_AMOUNT_BELOW_MINIMUM
  • 触发条件： 金额低于产品最低值
  • 消息： 金额不能低于产品规定的最低金额
• SUBSCRIPTION_EXPIRED
  • 触发条件： 计费超过 ends_at
  • 消息： 订阅已过期，无法创建新费用
• SUBSCRIPTION_INACTIVE
  • 触发条件： 状态不等于 ACTIVE
  • 消息： 订阅未激活
• SUBSCRIPTION_NOT_ON_DEMAND
  • 触发条件： 预期为按需，但得到的是固定间隔
  • 消息： 订阅已不再是按需
• SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
  • 触发条件： 订阅支付重试次数超过最大尝试次数
  • 消息： 该订阅已超过最多 10 次的重试限制
• TOO_MANY_REQUESTS
  • 触发条件： 触发 429 速率限制
  • 消息： 无消息
• TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
  • 触发条件： 合并购物车总额低于网关最低值
  • 消息： 处理支付需要至少 。
• UNABLE_TO_EDIT_PRIMARY_BRAND
  • 触发条件： 尝试通过普通 API 更新主品牌
  • 消息： 无法通过此 API 端点更新主品牌。
• UNAUTHORIZED
  • 触发条件： 未提供 API 密钥或令牌/作用域无效
  • 消息： 您无权限执行此操作
• UNSUPPORTED_ACTION
  • 触发条件： 资源类型不支持该操作
  • 消息： 不支持对基于用量的订阅更改计划
• UNSUPPORTED_BILLING_CURRENCY
  • 触发条件： 订阅仅限 USD
  • 消息： 非 USD 计费货币不支持订阅
• UNSUPPORTED_COUNTRY
  • 触发条件： 地域暂不支持
  • 消息： 当前不支持国家
• UNSUPPORTED_CURRENCY
  • 触发条件： 产品或插件货币无效
  • 消息： 当前不支持该货币 / 目前仅支持 USD 和 INR 产品 / 插件价格仅支持 USD 和 INR / billing_currency 只能请求 USD 或 INR / 不支持的货币 / 印度卡订阅的货币不符合预期
• UNSUPPORTED_DISCOUNT_TYPE
  • 触发条件： 固定金额折扣等尚未上线
  • 消息： 目前仅支持百分比折扣码
• UNSUPPORTED_PAYMENT_CURRENCY
  • 触发条件： 连接器阻止了该支付货币
  • 消息： 此交易不支持 INR 交易
• UNSUPPORTED_TAX_CATEGORY
  • 触发条件： 税务类别字符串未包含在枚举中
  • 消息： 当前不支持类别
• UNSUCCESSFUL_PAYMENT_ID
  • 触发条件： 支付 ID 引用未成功的支付
  • 消息： 该支付 ID 状态不成功
• ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
  • 触发条件： 尝试对金额为零的支付进行退款
  • 消息： 无法退款金额为零的支付

​

最佳实践

1. 在您的应用程序中始终优雅地处理错误
2. 实施适当的错误日志记录
3. 为最终用户使用适当的错误消息
4. 对瞬态错误实施重试逻辑
5. 联系支持以解决未解决的问题

​

支持