エラーコード

​

概要

• エラーの一般的なカテゴリを示すHTTPステータスコード
• エラーの正確な性質を特定する特定のエラーコード
• 何が問題だったのかを説明する人間が読めるエラーメッセージ
• 適用可能な場合、エラーに関する追加の詳細

• 統合の問題をデバッグする
• アプリケーションで適切なエラーハンドリングを実装する
• エンドユーザーに意味のあるフィードバックを提供する
• 堅牢な決済処理システムを維持する

​

標準APIエラーコード

​

エラーレスポンスフォーマット

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

​

エラーコードリファレンス

​

認証＆アカウント

• UNAUTHORIZED
  • トリガー: APIキーがないか、トークン/スコープが無効
  • メッセージ: この操作を行う権限がありません
• MERCHANT_NOT_LIVE
  • トリガー: ビジネスがまだテストモードになっている
  • メッセージ: マーチャントがまだ本番稼働していません

​

支払い＆チェックアウト

• CHECKOUT_SESSION_CONSUMED
  • トリガー: チェックアウトセッションが既に支払いを生成している
  • メッセージ: チェックアウトセッションは既に消費されています
• NO_ELIGIBLE_PAYMENT_METHODS
  • トリガー: フィルタリング後、何も残らない
  • メッセージ: 使用可能な支払い方法が見つかりません
• PAYMENT_NOT_SUCCEEDED
  • トリガー: 失敗した支払いを返金/処理しようとしている
  • メッセージ: 提供された支払いは成功していません
• PREVIOUS_PAYMENT_PENDING
  • トリガー: 非終端状態の前の支払いがある場合に新しい請求を作成しようとする
  • メッセージ: 前の支払いがまだ成功していないため、新しい請求を作成できません
• UNSUCCESSFUL_PAYMENT_ID
  • トリガー: 支払いIDが成功していない支払いを参照している
  • メッセージ: 支払いIDは成功していないステータスです。

​

コネクタ＆BYOP

• BYOP_CONNECTOR_DISABLED
  • トリガー: 無効化されたBYOPコネクタを通してルーティングされるサブスクリプションの支払い方法を更新しようとする
  • メッセージ: サブスクリプションは現在無効なマーチャントの独自（BYOP）コネクタを通してルーティングされています
• BYOP_CUSTOM_INVOICE_ADDRESS_MISSING
  • トリガー: マーチャントルーティング(BYOP)支払いに必要なカスタム請求書アドレスが欠落している
  • メッセージ: 支払いがマーチャントのコネクタを通してルーティングされる場合、BYOPカスタム請求書アドレスが必要です
• CONNECTOR_LABEL_ALREADY_EXISTS
  • トリガー: 既に存在するラベルでコネクタを作成しようとする
  • メッセージ: すでにこのラベルでコネクタがあります。異なるラベルを選択してください。

​

返金

• EXISTING_REFUND_REQUEST_PROCESSING
  • Trigger: 前回の返金リクエストがまだ処理中です
  • Message: ステータス「Pending」の返金リクエストがまだ処理中です
• LINE_ITEM_FULLY_REFUNDED
  • トリガー: 既に全額返金されたラインアイテムに対して返金を試みる
  • メッセージ: ラインアイテムはすでに全額返金されており、これ以上返金できません。
• LINE_ITEM_NOT_FOUND
  • トリガー: 参照された支払いに含まれていない項目ID
  • メッセージ: ラインアイテムは支払い内に見つかりません
• LINE_ITEM_PRORATED
  • トリガー: プロレートされたラインの返金または更新が試みられた
  • メッセージ: ラインアイテムはプロレートされているため返金できません
• LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
  • トリガー: 返金額が支払額（税を含む）を超えている
  • メッセージ: ラインアイテム要求された返金額（税を含む）はで、支払額を超えています
• LINE_ITEM_REFUND_AMOUNT_TOO_LOW
  • トリガー: 最低限度額未満の返金額
  • メッセージ: ラインアイテム要求された返金額はで、低すぎます
• NOTHING_TO_REFUND
  • トリガー: 返金額は残っておらず、すべての正のラインアイテムはすでに全額返金されています
  • メッセージ: 返金可能額は残っていません。すべての正のラインアイテムがすでに完全に返金されています。
• PARTIAL_REFUND_NOT_ALLOWED
  • トリガー: 部分返金が全額返金のみをサポートする支払い方法で試みられる
  • メッセージ: この支払い方法では部分返金は許可されていません
• PAYMENT_ALREADY_REFUNDED
  • トリガー: 重複した返金
  • メッセージ: この支払いはすでに返金されています
• PAYMENT_HAS_BEEN_REFUNDED
  • トリガー: 支払いは完全に返金されています
  • メッセージ: 支払いIDは完全に返金されています。
• REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT
  • トリガー: 集計返金額が支払額を超えている
  • メッセージ: 計算された返金額は支払額を超えています
• REFUND_WINDOW_EXPIRED
  • トリガー: 許可された返金ウィンドウ外
  • メッセージ: 支払い作成後日以内に返金を開始することはできません。support@dodopayments.comにご連絡ください。
• ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
  • トリガー: ゼロ金額の支払いを返金しようとする
  • メッセージ: ゼロ通貨量での支払いは返金できません

​

サブスクリプション＆アドオン

• ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
  • トリガー: 従量制課金サブスクリプションにアドオンを追加しようとする
  • メッセージ: 従量制課金にはサブスクリプションでアドオンはサポートされていません
• ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
  • トリガー: オンデマンドサブスクリプションにアドオンを追加しようとする
  • メッセージ: オンデマンドサブスクリプションにはアドオンは許可されていません
• CANCEL_SCHEDULED_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • トリガー: ビジネスがそのアクションを無効にしている間に顧客ポータルがスケジュールされたプラン変更をキャンセルしようとする
  • メッセージ: 顧客ポータルでのスケジュールされたプラン変更のキャンセルは無効になっています。
• CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • トリガー: キャンセルが予定されているサブスクリプションを請求しようとする
  • メッセージ: キャンセル予定のサブスクリプション
• CUSTOMER_HAS_EXISTING_SUBSCRIPTION
  • トリガー: すでにサブスクリプションを持つ顧客に対してサブスクリプションを作成する、顧客ごとに複数のサブスクリプションが許可されていない場合
  • メッセージ: 顧客には既存のサブスクリプションがあります。複数のサブスクリプションを顧客ごとに許可するには、ビジネス設定を変更してください
• DO_NOT_BILL_NOT_ALLOWED_IN_CUSTOMER_PORTAL
  • トリガー: 顧客ポータルプラン変更で使用されるdo_not_billプロレートモード
  • メッセージ: do_not_billプロレートモードは顧客ポータルで許可されていません
• DUPLICATE_ADDON_IDS_IN_REQUEST
  • トリガー: リクエストに同じaddon_idが複数回含まれる
  • メッセージ: 重複したアドオンIDは許可されていません
• INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
  • トリガー: 非アクティブなサブスクリプションでのプラン変更
  • メッセージ: 非アクティブなサブスクリプションではプランの変更はサポートされていません
• INVALID_PRORATION_MODE_WITH_NEXT_BILLING_DATE
  • トリガー: effective_at: next_billing_dateとともにfull_immediately以外のプロレートモードが使用される
  • メッセージ: 有効日：next_billing_dateでは、full_immediatelyプロレートモードのみ許可されています
• MISSING_ADDON_IDS
  • トリガー: addon_idリストが空または不明なID
  • メッセージ: 存在しない製品IDが1つまたは複数あります：
• ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
  • トリガー: オンデマンドにはプランスワップが許可されていません
  • メッセージ: オンデマンドサブスクリプションではプランの変更はサポートされていません
• ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
  • トリガー: 従量制課金でオンデマンドを使用しようとする
  • メッセージ: 従量制課金にはオンデマンドサブスクリプションはサポートされていません
• ONE_TIME_PRODUCTS_NOT_ALLOWED_FOR_ON_DEMAND
  • トリガー: オンデマンドサブスクリプションに一時的な製品を追加
  • メッセージ: オンデマンドサブスクリプションには一時製品は許可されていません
• PENDING_PLAN_CHANGE_EXISTS
  • トリガー: 以前のものが支払い待ちの間に新しいプラン変更が要求される
  • メッセージ: このサブスクリプションには保留中のプラン変更がすでに存在します。現在の支払いが完了するのを待ってください。
• PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • トリガー: ビジネスがそれを無効にしている間の顧客ポータルを通じたプラン変更
  • メッセージ: 顧客ポータルでのサブスクリプションプラン変更は無効になっています。
• PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • トリガー: 取消予定のサブスクリプションでのプラン変更が試みられる
  • メッセージ: 取消予定のサブスクリプション
• SCHEDULE_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • トリガー: ビジネスがそれを無効にしている間の顧客ポータルを通じたプラン変更のスケジューリング
  • メッセージ: このビジネス用のプラン変更のスケジューリングは無効になっています。
• SCHEDULED_PLAN_CHANGE_EXISTS
  • トリガー: 既存のスケジュールがある場合にプラン変更をスケジュールする
  • メッセージ: このサブスクリプションにはスケジュールされたプラン変更がすでに存在します。新しいものを作成する前に既存のスケジュールされた変更をキャンセルしてください。
• SCHEDULED_PLAN_CHANGE_NOT_FOUND
  • トリガー: 存在しないスケジュールされたプラン変更を参照またはキャンセルしようとする
  • メッセージ: このサブスクリプションにスケジュールされたプラン変更が見つかりません。
• SUBSCRIPTION_EXPIRED
  • トリガー: ends_atを超えて請求する
  • メッセージ: サブスクリプションの期限が切れているため新しい請求を作成できません
• SUBSCRIPTION_INACTIVE
  • トリガー: ステータス ≠ ACTIVE
  • メッセージ: サブスクリプションはアクティブではありません
• SUBSCRIPTION_NOT_ON_DEMAND
  • トリガー: オンデマンドを期待していたが固定された間隔が得られた
  • メッセージ: サブスクリプションはすでにオンデマンドではありません
• SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
  • トリガー: サブスクリプション支払いの再試行が最大試行回数を超えた
  • メッセージ: このサブスクリプションの最大10回の再試行制限を超過しました

​

製品、カート＆ブランド

• BRAND_MISMATCH
  • トリガー: カートアイテムが異なるブランドに属している
  • メッセージ: 商品カート内のすべてのアイテムは同じブランドに属する必要があります
• BRAND_NOT_ENABLED
  • トリガー: ブランドが無効またはアクティブではない
  • メッセージ: 提供されたブランドは有効ではありません
• BRAND_SUBMISSION_NOT_ENABLED
  • トリガー: ブランド検証の再提出機能が無効
  • メッセージ: ブランド検証の再提出は無効です
• FILE_IN_USE
  • Trigger: アクティブな entitlement grant から参照されている digital product file を削除しようとした
  • Message: Digital file is referenced by active grants
• INVALID_SUGGESTED_PRICE
  • トリガー: PWYW価格 < 許可される最低価格
  • メッセージ: 推奨価格は最低価格未満にすることはできません。支払いたい価格の場合、価格は最小受入額と見なされます
• LOCALIZED_PRICE_ALREADY_EXISTS
  • トリガー: この製品と国/通貨に対するローカライズ価格が既に存在する
  • メッセージ: この製品と国/通貨に対するローカライズ価格は既に存在します
• LOCALIZED_PRICE_DUPLICATES_BASE
  • トリガー: ローカライズ価格が製品の基本通貨/国を複製する
  • メッセージ: ローカライズ価格は製品の基本通貨/国を複製しています
• LOCALIZED_PRICE_SHAPE_MISMATCH
  • トリガー: ローカライズ価格の形状が製品のpricing_modeと一致しない
  • メッセージ: ローカライズ価格の形状は製品のpricing_modeと一致しません
• MISSING_PRODUCT_INFORMATION
  • トリガー: 製品が存在しているが、必須情報が不足している
  • メッセージ: 製品が存在していますが、他の必須情報が不足しているか無効です
• PAY_AS_YOU_WANT_AMOUNT_REQUIRED
  • トリガー: PWYW製品の価格が不足している
  • メッセージ: 支払いたい製品には金額が必須です
• PRODUCT_CART_EMTPY
  • トリガー: 空の製品カートが提出された
  • メッセージ: product_cartは空です（エラーコードはAPIが返す正確な値に一致するように意図的にEMTPYとスペルされています）
• PRODUCT_COLLECTION_IS_DELETED
  • トリガー: 削除された製品コレクションを操作する
  • メッセージ: メッセージなし
• PRODUCT_COLLECTION_MUST_HAVE_PRODUCTS
  • トリガー: コレクションから最後の製品（または製品を含む最後のグループ）を削除する
  • メッセージ: コレクションから最後の製品を削除することはできません。代わりにコレクションをアーカイブしてください。
• PRODUCT_IS_DELETED
  • トリガー: 製品のソフト削除
  • メッセージ: メッセージなし
• PRODUCT_PRICING_MODE_REQUIRED
  • トリガー: 製品のpricing_modeが設定される前にローカライズ価格を追加する
  • メッセージ: 製品のpricing_modeはローカライズ価格を追加する前に設定する必要があります
• SLUG_ALREADY_TAKEN
  • トリガー: 要求された製品スラッグ/短縮URLが既に使用されています
  • メッセージ: スラッグがすでに使用されています
• UNABLE_TO_EDIT_PRIMARY_BRAND
  • トリガー: 一次ブランドを通常のAPIを通して更新しようとする
  • メッセージ: 一次ブランドはこのAPIエンドポイントを通して更新できません。

​

割引

• DISCOUNT_ALREADY_USED_ON_SUBSCRIPTION
  • トリガー: このサブスクリプションで既に使用されている割引を再適用する
  • メッセージ: このサブスクリプションでこの割引はすでに使用されています
• DISCOUNT_CODE_ALREADY_EXISTS
  • トリガー: 割引コードの重複作成
  • メッセージ: 割引コードはすでに存在します
• DISCOUNT_CODE_EXPIRED
  • トリガー: 割引コードがそのexpires_atの日付を過ぎている
  • メッセージ: 割引コードは期限切れです
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • Trigger: usage_limit に到達した後に Discount を再利用した
  • Message: Usage limit cannot be less than times_used / Discount code hit usage limit
  • Note: Terminal — code は使い切られています。再試行しないでください。
• DISCOUNT_CONCURRENT_REDEMPTION
  • トリガー: 同じコードの別の引き換え処理が使用制限行のロックを長時間保持していた
  • メッセージ: 割引が同時に引き換えられています。再試行してください
  • 注: 一時的なエラーです。コードにはまだ利用可能な枠が残っている可能性があるため、リクエストを安全に再試行できます。これを「コードを使い切った」として顧客に表示しないでください。
• DISCOUNT_CURRENCY_OPTION_INVALID
  • Trigger: create または update で無効な currency_options
  • Message: A flat discount requires at least one currency option with a resolvable default / Duplicate currency options are not allowed / Only one currency option may be marked as default
• DISCOUNT_CUSTOMER_NOT_ELIGIBLE
  • Trigger: Customer が code の customer_eligibility を満たしていない（first_time、existing、または specific code の allow list に含まれていない）
  • Message: Customer is not eligible for this discount code
• DISCOUNT_MINIMUM_SUBTOTAL_NOT_MET
  • Trigger: Cart subtotal が checkout currency に設定された minimum_subtotal を下回っている
  • Message: Cart subtotal is below the discount’s minimum required subtotal
• DISCOUNT_NOT_YET_ACTIVE
  • Trigger: starts_at date より前に code を使用した
  • Message: Discount code is not yet active (starts_at is in the future)
• DISCOUNT_PER_CUSTOMER_USAGE_LIMIT_EXCEEDED
  • Trigger: Customer がすでに code を per_customer_usage_limit 回 redemption している
  • Message: Per-customer usage limit exceeded for this discount code
• DISCOUNT_NOT_APPLICABLE_TO_NEW_PRODUCT
  • Trigger: 既存の Discount が適用されない product への Plan change
  • Message: Discount not applicable to the new plan’s product
• DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
  • Trigger: on-demand subscription に code を適用した
  • Message: Discount coupon not available for on demand subscriptions
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • Trigger: 関係のない product(s) に code を適用した
  • Message: Discount coupon not available for this product
• INVALID_DISCOUNT_CODE
  • Trigger: Code が存在しない、または適用できない
  • Message: Invalid Discount Code / Discount Code cannot be applied to any product in the cart
• INVALID_PERCENTAGE
  • Trigger: Percent amount > 100%（または 10,000 basis points）
  • Message: Percentage amount cannot be more than 10000 / Discount code amount cannot be more than 100%
• UNSUPPORTED_DISCOUNT_TYPE
  • Trigger: サポートされていない Discount type。percentage と flat はどちらもサポートされていますが、per-unit amount discount はサポートされていません。
  • Message: Only percentage and flat discount codes are supported

​

License Keys

• ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT
  • Trigger: License-key activation：new limit < existing instance count
  • Message: New activation limit cannot be less than current instances count
• INACTIVE_LICENSE_KEY
  • Trigger: Key status ≠ ACTIVE
  • Message: License key is not active
• LICENSE_KEY_LIMIT_REACHED
  • Trigger: Activations = limit
  • Message: License key activation limit reached
• LICENSE_KEY_NOT_FOUND
  • Trigger: Instance ID または key ID が無効
  • Message: License key instance not found or does not belong to this license key
• NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
  • Trigger: sub-based key に expiry を設定しようとした
  • Message: Cannot set expiry date for subscription-based license key

​

Usage-Based Billing & Meters

• DUPLICATE_METER_IDS_IN_REQUEST
  • Trigger: 同じ meter ID がリクエスト内に複数回登場している
  • Message: Duplicate Meter Ids are not allowed
• INVALID_QUANTITY
  • Trigger: usage-based pricing に無効な quantity が指定されている
  • Message: Only 1 quantity allowed in usage based price products
• METER_IS_DELETED
  • Trigger: deleted meter を使用しようとした
  • Message: The Meter is already been deleted
• MISSING_METER_IDS
  • Trigger: Meter ID list が空、または無効な ID を含んでいる
  • Message: One or more meter IDs do not exist:

​

Credit-Based Billing

• CREDIT_ENTITLEMENT_IS_DELETED
  • Trigger: 削除された credit entitlement を操作している
  • Message: The credit entitlement has already been deleted
• CREDIT_ENTITLEMENT_NAME_ALREADY_EXISTS
  • Trigger: すでに存在する name で credit entitlement を作成しようとした
  • Message: A credit entitlement with this name already exists
• OVERAGE_LIMIT_EXCEEDED
  • Trigger: usage または credit deduction が設定された overage limit を超える
  • Message: Overage limit exceeded

​

Wallet

• INSUFFICIENT_WALLET_FUNDS
  • Trigger: Wallet balance < debit amount
  • Message: Insufficient funds in wallet
• NEGATIVE_BALANCE_ADJUSTMENT
  • Trigger: wallet balance を負の値にしようとした
  • Message: Wallet balance is not allowed to be made negative

​

Currency, Tax & Region

• EXCHANGE_RATE_NOT_FOUND
  • Trigger: from → to currency pair の FX rate がない
  • Message: Exchange rate not found to convert from Currency to Currency
• INVALID_TAX_ID
  • Trigger: VAT/GST/TIN の validation に失敗した
  • Message: Tax Id is invalid
• REQUEST_AMOUNT_BELOW_MINIMUM
  • Trigger: Amount < product minimum
  • Message: Amount cannot be less than minimum amount specified for the product
• TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
  • Trigger: Combined cart total < gateway minimum
  • Message: Minimum amount of is required to process payment
• UNSUPPORTED_BILLING_CURRENCY
  • Trigger: リクエストされた billing currency はこの subscription でサポートされていない
  • Message: Non USD billing currency is not supported for subscriptions
• UNSUPPORTED_COUNTRY
  • Trigger: Geo がまだサポートされていない
  • Message: Country currently not supported
• UNSUPPORTED_CURRENCY
  • Trigger: Product または addon の currency が、Dodo Payments が charge できる currency ではない。Base prices は chargeable currency であれば設定できるため、通常は currency code が無効であるか、まだサポートされていないことを意味する。
  • Message: Currency is not currently supported / Only USD and INR products supported currently / Only USD and INR supported for addon price / Can only request USD or INR for billing_currency / Currency Not Supported / Unexpected currency for Indian card subscriptions
• UNSUPPORTED_TAX_CATEGORY
  • Trigger: Tax category string が enum に含まれていない
  • Message: Category currently not supported

​

Validation & Requests

• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • Trigger: 同じ item_id が items[] に 2 回登場している
  • Message: Duplicate item_ids specified in items array
• INVALID_QUERY_PARAMS
  • Trigger: 相互排他的、または形式が正しくない query parameters
  • Message: Query params should only contain either time_frame or (start, end)
• INVALID_REQUEST_BODY
  • Trigger: JSON の形式が正しくないか、schema に違反している
  • Message: Your request body is invalid. Please check your request headers and object.
• INVALID_REQUEST_PARAMETERS
  • Trigger: Semantics が正しくない（例：過去の日付）
  • Message: Cannot change next_billing_date to past time
• MAXIMUM_KEYS_REACHED
  • Trigger: Metadata / custom-fields が 50 ペアを超えている
  • Message: Exceeds 50 key-value pairs

​

General & System

• INTEGER_CONVERSION_FAILURE
  • Trigger: サーバー側で失敗した integer ↔ string/decimal conversion
  • Message: Integer Conversion Failure
• INTERNAL_SERVER_ERROR
  • Trigger: 捕捉されていない exception。サーバー側で詳細を log に記録してください
  • Message: No public message (generic 500)
• NOT_FOUND
  • Trigger: 欠落しているリソースに対する一般的な 404
  • Message: Item not found (or more specific)
• TOO_MANY_REQUESTS
  • Trigger: 429 rate-limit
  • Message: No messages
• UNSUPPORTED_ACTION
  • Trigger: リソース type でサポートされていない action
  • Message: Changing plans for usage based subscriptions is not supported

​

Best Practices

1. アプリケーションで常にエラーを適切に処理する
2. 適切な error logging を実装する
3. end user に適切な error messages を使用する
4. transient errors に対する retry logic を実装する
5. 解決しない問題については support に問い合わせる

​

Support