Mã Lỗi

​

Tổng Quan

• Mã trạng thái HTTP chỉ ra danh mục chung của lỗi
• Mã lỗi cụ thể xác định chính xác bản chất của lỗi
• Thông điệp lỗi dễ hiểu giải thích điều gì đã sai
• Thông tin chi tiết bổ sung về lỗi khi có thể

• Gỡ lỗi các vấn đề tích hợp
• Triển khai xử lý lỗi đúng cách trong ứng dụng của bạn
• Cung cấp phản hồi có ý nghĩa cho người dùng cuối
• Duy trì một hệ thống xử lý thanh toán vững chắc

​

Mã Lỗi API Tiêu Chuẩn

​

Định Dạng Phản Hồi Lỗi

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

​

Tham Khảo Mã Lỗi

• ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT
  • Trigger: Kích hoạt khóa giấy phép: giới hạn mới < số lượng phiên bản hiện có
  • Message: Giới hạn kích hoạt mới không thể thấp hơn số lượng phiên bản hiện tại
• ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Trigger: Cố gắng thêm addon vào đăng ký thanh toán theo sử dụng
  • Message: Addon trong đăng ký không được hỗ trợ cho thanh toán theo sử dụng
• ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
  • Trigger: Cố gắng thêm addon vào đăng ký theo yêu cầu
  • Message: Addon không được phép cho đăng ký theo yêu cầu
• BRAND_MISMATCH
  • Trigger: Các mục giỏ hàng thuộc các thương hiệu khác nhau
  • Message: Tất cả mục trong giỏ hàng phải thuộc cùng một thương hiệu
• BRAND_NOT_ENABLED
  • Trigger: Thương hiệu bị vô hiệu hóa hoặc không hoạt động
  • Message: Thương hiệu cung cấp chưa được bật
• BRAND_SUBMISSION_NOT_ENABLED
  • Trigger: Tính năng nộp lại xác thực thương hiệu chưa được bật
  • Message: Tính năng nộp lại xác thực thương hiệu chưa được bật
• CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Trigger: Cố gắng tính phí đăng ký đã được lên lịch hủy
  • Message: Đăng ký đã được lên lịch hủy
• CHECKOUT_SESSION_CONSUMED
  • Trigger: Phiên thanh toán đã tạo thanh toán
  • Message: Phiên thanh toán đã được sử dụng
• DISCOUNT_CODE_ALREADY_EXISTS
  • Trigger: Tạo mã giảm giá trùng lặp
  • Message: Mã giảm giá đã tồn tại
• DISCOUNT_CODE_EXPIRED
  • Trigger: Mã giảm giá đã quá expires_at
  • Message: Mã giảm giá hết hạn
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • Trigger: Mã giảm giá được sử dụng lại sau khi usage_limit đạt
  • Message: Giới hạn sử dụng không thể nhỏ hơn times_used / Mã giảm giá đã đạt giới hạn sử dụng
• DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
  • Trigger: Mã áp dụng cho đăng ký theo yêu cầu
  • Message: Coupon giảm giá không có sẵn cho đăng ký theo yêu cầu
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • Trigger: Mã áp dụng cho sản phẩm không liên quan
  • Message: Coupon giảm giá không có sẵn cho sản phẩm này
• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • Trigger: Cùng item_id xuất hiện hai lần trong items[]
  • Message: Chỉ định trùng lặp item_ids trong mảng items
• DUPLICATE_METER_IDS_IN_REQUEST
  • Trigger: Cùng Meter ID xuất hiện nhiều lần trong yêu cầu
  • Message: Không cho phép Meter Id trùng lặp
• EXCHANGE_RATE_NOT_FOUND
  • Trigger: Không có tỷ giá FX cho cặp tiền tệ from → to
  • Message: Không tìm thấy tỷ giá để chuyển đổi từ Currency sang Currency
• EXISTING_REFUND_REQUEST_PROCESSING
  • Trigger: Yêu cầu hoàn tiền trước vẫn đang được xử lý
  • Message: Yêu cầu hoàn tiền với trạng thái “Pending” vẫn đang được xử lý
• INACTIVE_LICENSE_KEY
  • Trigger: Trạng thái khóa ≠ ACTIVE
  • Message: Khóa giấy phép không hoạt động
• INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
  • Trigger: Đổi gói trên đăng ký không hoạt động
  • Message: Không hỗ trợ đổi gói cho đăng ký không hoạt động
• INSUFFICIENT_WALLET_FUNDS
  • Trigger: Số dư ví < số tiền ghi nợ
  • Message: Không đủ tiền trong ví
• INTEGER_CONVERSION_FAILURE
  • Trigger: Bất kỳ chuyển đổi số nguyên ↔ chuỗi/số thập phân nào bị lỗi phía máy chủ
  • Message: Lỗi chuyển đổi số nguyên
• INTERNAL_SERVER_ERROR
  • Trigger: Ngoại lệ chưa được xử lý; bạn nên ghi nhật ký chi tiết phía máy chủ
  • Message: Không có thông điệp công khai (500 chung)
• INVALID_DISCOUNT_CODE
  • Trigger: Mã không tồn tại / không áp dụng được
  • Message: Mã giảm giá không hợp lệ / Mã giảm giá không thể áp dụng cho bất kỳ sản phẩm nào trong giỏ hàng
• INVALID_PERCENTAGE
  • Trigger: Số phần trăm > 100% (hoặc 10.000 điểm cơ bản)
  • Message: Số phần trăm không thể vượt quá 10000 / Số tiền mã giảm giá không thể vượt quá 100%
• INVALID_QUANTITY
  • Trigger: Số lượng không hợp lệ cho giá theo sử dụng
  • Message: Chỉ cho phép số lượng 1 trong sản phẩm giá theo sử dụng
• INVALID_QUERY_PARAMS
  • Trigger: Tham số truy vấn loại trừ lẫn nhau / sai định dạng
  • Message: Tham số truy vấn chỉ nên chứa time_frame hoặc (start, end)
• INVALID_REQUEST_BODY
  • Trigger: JSON sai định dạng hoặc vi phạm schema
  • Message: Body yêu cầu của bạn không hợp lệ. Vui lòng kiểm tra header và đối tượng yêu cầu.
• INVALID_REQUEST_PARAMETERS
  • Trigger: Ngữ nghĩa sai (ví dụ: ngày ở quá khứ)
  • Message: Không thể thay đổi next_billing_date thành thời gian trong quá khứ
• INVALID_SUGGESTED_PRICE
  • Trigger: Giá PWYW < mức tối thiểu cho phép
  • Message: Giá đề xuất không thể thấp hơn giá tối thiểu. Trong trường hợp trả bao nhiêu tùy ý, giá được xem là số tiền tối thiểu chấp nhận được
• INVALID_TAX_ID
  • Trigger: VAT/GST/TIN xác thực thất bại
  • Message: Mã số thuế không hợp lệ
• LICENSE_KEY_LIMIT_REACHED
  • Trigger: Số lượt kích hoạt = giới hạn
  • Message: Đạt giới hạn kích hoạt khóa giấy phép
• LICENSE_KEY_NOT_FOUND
  • Trigger: ID phiên bản hoặc ID khóa không hợp lệ
  • Message: Không tìm thấy phiên bản khóa giấy phép hoặc không thuộc khóa này
• LINE_ITEM_FULLY_REFUNDED
  • Trigger: Cố gắng hoàn tiền cho mục dòng đã hoàn tiền toàn bộ
  • Message: Mục dòng đã được hoàn tiền đầy đủ không thể hoàn thêm.
• LINE_ITEM_NOT_FOUND
  • Trigger: ID mục không thuộc khoản thanh toán tham chiếu
  • Message: Không tìm thấy mục dòng trong khoản thanh toán
• LINE_ITEM_PRORATED
  • Trigger: Cố gắng hoàn tiền/cập nhật trên dòng đã tính tỷ lệ
  • Message: Mục dòng không thể hoàn tiền vì đã được tính tỷ lệ
• LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
  • Trigger: Số tiền hoàn > số tiền đã trả (bao gồm thuế)
  • Message: Số tiền hoàn yêu cầu cho mục dòng bao gồm thuế là cao hơn số tiền đã thanh toán
• LINE_ITEM_REFUND_AMOUNT_TOO_LOW
  • Trigger: Số tiền hoàn dưới ngưỡng tối thiểu
  • Message: Số tiền hoàn yêu cầu cho mục dòng là quá thấp
• MAXIMUM_KEYS_REACHED
  • Trigger: Metadata/custom-fields vượt quá 50 cặp
  • Message: Vượt quá 50 cặp khóa-giá trị
• MERCHANT_NOT_LIVE
  • Trigger: Doanh nghiệp vẫn ở chế độ kiểm thử/sandbox
  • Message: Thương nhân chưa hoạt động thật
• METER_IS_DELETED
  • Trigger: Cố gắng sử dụng đồng hồ đo đã xóa
  • Message: Đồng hồ đo đã bị xóa
• MISSING_ADDON_IDS
  • Trigger: addon_id danh sách trống hoặc ID không xác định
  • Message: Một hoặc nhiều ID sản phẩm không tồn tại:
• MISSING_METER_IDS
  • Trigger: Danh sách ID đồng hồ đo trống hoặc chứa ID không hợp lệ
  • Message: Một hoặc nhiều ID đồng hồ đo không tồn tại:
• MISSING_PRODUCT_INFORMATION
  • Trigger: Sản phẩm tồn tại nhưng thiếu thông tin bắt buộc
  • Message: Sản phẩm tồn tại nhưng thông tin bắt buộc khác bị thiếu hoặc không hợp lệ
• NEGATIVE_BALANCE_ADJUSTMENT
  • Trigger: Cố gắng làm số dư ví âm
  • Message: Không cho phép số dư ví âm
• NO_ELIGIBLE_PAYMENT_METHODS
  • Trigger: Sau khi lọc, không còn gì
  • Message: Không tìm thấy phương thức thanh toán hợp lệ
• NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
  • Trigger: Cố gắng đặt ngày hết hạn cho khóa dựa trên đăng ký
  • Message: Không thể đặt ngày hết hạn cho khóa giấy phép dựa trên đăng ký
• NOT_FOUND
  • Trigger: 404 chung cho bất kỳ tài nguyên nào bị thiếu
  • Message: Không tìm thấy mục (hoặc cụ thể hơn)
• ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
  • Trigger: Không cho phép đổi gói cho đăng ký theo yêu cầu
  • Message: Không hỗ trợ đổi gói cho đăng ký theo yêu cầu
• ON_DEMAND_SUBSCRIPTIONS_NOT_ENABLED
  • Trigger: Doanh nghiệp đã tắt cờ tính năng
  • Message: Đăng ký theo yêu cầu chưa được bật cho doanh nghiệp này
• ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Trigger: Cố gắng sử dụng đăng ký theo yêu cầu với thanh toán theo sử dụng
  • Message: Đăng ký theo yêu cầu không được hỗ trợ cho thanh toán theo sử dụng
• PAY_AS_YOU_WANT_AMOUNT_REQUIRED
  • Trigger: Thiếu giá cho sản phẩm PWYW
  • Message: Số tiền là bắt buộc cho sản phẩm trả bao nhiêu tùy ý
• PAYMENT_ALREADY_REFUNDED
  • Trigger: Hoàn tiền trùng lặp
  • Message: Khoản thanh toán này đã được hoàn tiền
• PAYMENT_HAS_BEEN_REFUNDED
  • Trigger: Khoản thanh toán đã được hoàn tiền toàn bộ
  • Message: ID khoản thanh toán đã được hoàn tiền toàn bộ.
• PAYMENT_NOT_SUCCEEDED
  • Trigger: Cố gắng hoàn tiền/xử lý khoản thanh toán không thành công
  • Message: Khoản thanh toán được cung cấp chưa thành công
• PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Trigger: Cố gắng đổi gói trên đăng ký đã lên lịch hủy
  • Message: Đăng ký đã được lên lịch hủy
• PREVIOUS_PAYMENT_PENDING
  • Trigger: Cố gắng tạo phí khi khoản trước chưa ở trạng thái kết thúc
  • Message: Không thể tạo khoản phí mới vì khoản thanh toán trước chưa thành công
• PRODUCT_CART_EMPTY
  • Trigger: Gửi giỏ sản phẩm trống
  • Message: product_cart trống
• PRODUCT_IS_DELETED
  • Trigger: Sản phẩm bị xóa mềm
  • Message: Không có thông điệp
• REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT
  • Trigger: Tổng số tiền hoàn > số tiền đã trả
  • Message: Số tiền hoàn tính toán lớn hơn số tiền đã thanh toán
• REFUND_WINDOW_EXPIRED
  • Trigger: Ngoài khoảng chấp nhận hoàn tiền
  • Message: Không thể khởi tạo hoàn tiền ngày sau khi tạo khoản thanh toán. Liên hệ support@dodopayments.com.
• REQUEST_AMOUNT_BELOW_MINIMUM
  • Trigger: Số tiền < mức tối thiểu của sản phẩm
  • Message: Số tiền không thể thấp hơn mức tối thiểu được chỉ định cho sản phẩm
• SUBSCRIPTION_EXPIRED
  • Trigger: Thanh toán quá ends_at
  • Message: Đăng ký hết hạn không thể tạo khoản phí mới
• SUBSCRIPTION_INACTIVE
  • Trigger: Trạng thái ≠ ACTIVE
  • Message: Đăng ký không hoạt động
• SUBSCRIPTION_NOT_ON_DEMAND
  • Trigger: Mong đợi đăng ký theo yêu cầu nhưng nhận được khoảng cố định
  • Message: Đăng ký hiện không còn theo yêu cầu
• SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
  • Trigger: Thử lại thanh toán đăng ký vượt quá số lần tối đa
  • Message: Đã vượt quá giới hạn thử lại tối đa 10 lần cho đăng ký này
• TOO_MANY_REQUESTS
  • Trigger: Giới hạn tần suất 429
  • Message: Không có thông điệp
• TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
  • Trigger: Tổng giỏ hàng nhỏ hơn mức tối thiểu của cổng thanh toán
  • Message: Cần tối thiểu để xử lý thanh toán
• UNABLE_TO_EDIT_PRIMARY_BRAND
  • Trigger: Cố gắng cập nhật thương hiệu chính qua API thường
  • Message: Không thể cập nhật thương hiệu chính qua endpoint API này.
• UNAUTHORIZED
  • Trigger: Không có API key hoặc token/phạm vi không hợp lệ
  • Message: Bạn không được phép thực hiện hành động này
• UNSUPPORTED_ACTION
  • Trigger: Hành động không được hỗ trợ cho loại tài nguyên
  • Message: Không hỗ trợ đổi gói cho đăng ký theo sử dụng
• UNSUPPORTED_BILLING_CURRENCY
  • Trigger: Đăng ký giới hạn ở USD
  • Message: Tiền tệ thanh toán không phải USD không được hỗ trợ cho đăng ký
• UNSUPPORTED_COUNTRY
  • Trigger: Khu vực chưa được hỗ trợ
  • Message: Quốc gia hiện không được hỗ trợ
• UNSUPPORTED_CURRENCY
  • Trigger: Tiền tệ sản phẩm hoặc addon không hợp lệ
  • Message: Tiền tệ hiện không được hỗ trợ / Hiện chỉ hỗ trợ sản phẩm USD và INR / Chỉ hỗ trợ USD và INR cho giá addon / Chỉ có thể yêu cầu USD hoặc INR cho billing_currency / Tiền tệ không được hỗ trợ / Tiền tệ không hợp lệ cho đăng ký thẻ Ấn Độ
• UNSUPPORTED_DISCOUNT_TYPE
  • Trigger: Mã giảm giá cố định chưa ra mắt
  • Message: Hiện chỉ hỗ trợ mã giảm giá theo phần trăm
• UNSUPPORTED_PAYMENT_CURRENCY
  • Trigger: Tiền tệ thanh toán bị chặn cho bộ nối
  • Message: Giao dịch INR không được hỗ trợ cho giao dịch này
• UNSUPPORTED_TAX_CATEGORY
  • Trigger: Chuỗi danh mục thuế không nằm trong enum
  • Message: Danh mục hiện không được hỗ trợ
• UNSUCCESSFUL_PAYMENT_ID
  • Trigger: ID thanh toán tham chiếu thanh toán không thành công
  • Message: ID khoản thanh toán có trạng thái không thành công.
• ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
  • Trigger: Cố gắng hoàn tiền cho khoản thanh toán có số tiền 0
  • Message: Không thể hoàn tiền cho khoản thanh toán có số tiền bằng không

​

Thực Hành Tốt Nhất

1. Luôn xử lý lỗi một cách khéo léo trong ứng dụng của bạn
2. Triển khai ghi nhật ký lỗi đúng cách
3. Sử dụng thông điệp lỗi phù hợp cho người dùng cuối
4. Triển khai logic thử lại cho các lỗi tạm thời
5. Liên hệ với hỗ trợ cho các vấn đề chưa được giải quyết

​

Hỗ Trợ