错误代码

​

概述

• 指示错误一般类别的 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
  • 触发器： 折扣代码过期
  • 消息： 折扣代码已过期
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • 触发器： 折扣在达到使用限制后被重复使用
  • 消息： 使用限制不能少于 times_used / 折扣代码命中使用限制
• DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
  • 触发器： 代码应用于按需订阅
  • 消息： 折扣券不适用于按需订阅
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • 触发器： 代码应用于不相关的产品
  • 消息： 折扣券不适用于此产品
• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • 触发器： 相同的 item_id 在 items[] 中出现两次
  • 消息： 在项目数组中指定了重复的 item_ids
• DUPLICATE_METER_IDS_IN_REQUEST
  • 触发器： 请求中出现多个相同的计量 ID
  • 消息： 不允许重复的计量 ID
• EXCHANGE_RATE_NOT_FOUND
  • 触发器： 没有 from → to 货币对的外汇汇率
  • 消息： 找不到汇率以从货币转换为货币
• EXISTING_REFUND_REQUEST_PROCESSING
  • 触发器： 先前的退款请求仍在处理中
  • 消息： 状态为 “待处理” 的退款请求仍在处理中
• 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
  • 触发器： 互斥/格式不正确的查询参数
  • 消息： 查询参数应仅包含时间范围或（开始，结束）中的一个
• INVALID_REQUEST_BODY
  • 触发器： 格式不正确的 JSON 或模式违规
  • 消息： 您的请求体无效。请检查您的请求头和对象。
• INVALID_REQUEST_PARAMETERS
  • 触发器： 语义错误（例如，日期在过去）
  • 消息： 不能将 next_billing_date 更改为过去的时间
• INVALID_SUGGESTED_PRICE
  • 触发器： PWYW 价格 < 最低允许价格
  • 消息： 建议价格不能低于最低价格。在您想要支付的情况下，价格被视为最低接受金额
• 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 产品缺少价格
  • 消息： 金额是您想要支付的产品的强制项
• 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
  • 触发器： 超出允许的退款窗口
  • 消息： 退款不能在付款创建后 天内发起。请联系 [email protected]。
• 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 附加组件价格/只能请求 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. 联系支持以解决未解决的问题

​

支持