エラーコード

​

概要

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

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

​

標準APIエラーコード

​

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

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

​

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

​

認証＆アカウント

• UNAUTHORIZED
  • トリガー: APIキーがないか、トークン/スコープが無効
  • メッセージ: この操作を行う権限がありません
• MERCHANT_NOT_LIVE
  • トリガー: ビジネスがまだテストモードになっている
  • メッセージ: マーチャントがまだ本番稼働していません
• BUSINESS_ARCHIVED
  • Trigger: アーカイブ済みのビジネスに対する、顧客向けのあらゆるリクエスト（checkout、payment link、storefront、Customer Portal、または license key）
  • Message: このビジネスはアーカイブ済みで、リクエストを受け付けていません

​

Payments & Checkout

• CHECKOUT_SESSION_CONSUMED
  • Trigger: Checkout session がすでに payment を生成している
  • Message: Checkout session はすでに使用されています
• NO_ELIGIBLE_PAYMENT_METHODS
  • Trigger: フィルタリング後に残っているものがない
  • Message: 利用可能な payment methods が見つかりません
• PAYMENT_NOT_SUCCEEDED
  • Trigger: 失敗した payment の refund または処理を試行した
  • Message: 指定された payment は成功していません
• PREVIOUS_PAYMENT_PENDING
  • Trigger: 前の payment が終端状態ではない間に charge の作成を試行した
  • Message: 前の payment がまだ成功していないため、新しい charge を作成できません
• UNSUCCESSFUL_PAYMENT_ID
  • Trigger: Payment ID が失敗した payment を参照している
  • Message: Payment ID の status は失敗です。

​

Connectors & BYOP

• BYOP_CONNECTOR_DISABLED
  • Trigger: 無効化された BYOP connector 経由の subscription で payment method を更新しようとした
  • Message: この subscription は merchant 独自の（BYOP）connector 経由でルーティングされていますが、現在無効です
• BYOP_CUSTOM_INVOICE_ADDRESS_MISSING
  • Trigger: merchant 経由の（BYOP）payment に必要な custom invoice address がない
  • Message: payment が merchant の connector 経由でルーティングされる場合、BYOP custom invoice address が必要です
• CONNECTOR_LABEL_ALREADY_EXISTS
  • Trigger: すでに存在する label で connector を作成しようとした
  • Message: この label の connector はすでに存在します。別の label を選択してください。

​

Refunds

• EXISTING_REFUND_REQUEST_PROCESSING
  • Trigger: 前回の refund request がまだ処理中
  • Message: status が “Pending” の refund request はまだ処理中です
• LINE_ITEM_FULLY_REFUNDED
  • Trigger: すでに全額 refund 済みの line item を refund しようとした
  • Message: Line item は全額 refund 済みのため、これ以上 refund できません。
• LINE_ITEM_NOT_FOUND
  • Trigger: Item ID が参照された payment の一部ではない
  • Message: payment に Line item が見つかりません
• LINE_ITEM_PRORATED
  • Trigger: prorated line に対して refund または update を試行した
  • Message: Line item は prorated のため refund できません
• LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
  • Trigger: Refund amount > paid amount（tax を含む）
  • Message: Line item の requested refund amount（tax を含む）は で、paid amount を超えています
• LINE_ITEM_REFUND_AMOUNT_TOO_LOW
  • Trigger: Refund amount が最小しきい値を下回っている
  • Message: Line item の requested refund amount は で、低すぎます
• NOTHING_TO_REFUND
  • Trigger: refund 可能な amount が残っていない。すべての正の line item がすでに全額 refund 済み
  • Message: refund 可能な amount が残っていません。すべての正の line item は全額 refund 済みです。
• PARTIAL_REFUND_NOT_ALLOWED
  • Trigger: full refund のみをサポートする payment method に対して partial refund を試行した
  • Message: この payment method では partial refund は許可されていません
• PAYMENT_ALREADY_REFUNDED
  • Trigger: 重複した refund
  • Message: この payment はすでに refund 済みです
• PAYMENT_HAS_BEEN_REFUNDED
  • Trigger: payment が全額 refund 済み
  • Message: Payment ID は全額 refund 済みです。
• REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT
  • Trigger: Aggregate refund amount > paid amount
  • Message: calculated refund amount が paid amount より大きくなっています
• REFUND_WINDOW_EXPIRED
  • Trigger: 許可された refund 期間外
  • Message: payment の作成から 日を過ぎると refund を開始できません。support@dodopayments.com にお問い合わせください。
• ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
  • Trigger: zero-amount payment を refund しようとした
  • Message: currency amount がゼロの payment は refund できません

​

Subscriptions & Add-ons

• ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Trigger: usage-based billing subscription に addons を追加しようとした
  • Message: Usage Based Billing の Subscriptions では addons はサポートされていません
• ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
  • Trigger: on-demand subscription に addons を追加しようとした
  • Message: on demand subscription では addons は許可されていません
• CANCEL_SCHEDULED_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Trigger: business がその操作を無効にしている間に、Customer Portal が scheduled plan change のキャンセルを試行した
  • Message: customer portal での scheduled plan change のキャンセルは無効です。
• CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Trigger: キャンセル予定の subscription に charge しようとした
  • Message: Subscription はキャンセル予定です
• CUSTOMER_HAS_EXISTING_SUBSCRIPTION
  • Trigger: 複数の subscription が customer に許可されていない場合に、すでに subscription を持つ customer の subscription を作成しようとした
  • Message: Customer には既存の subscription があります。customer ごとに複数の subscription を許可するには、business settings を変更してください
• DO_NOT_BILL_NOT_ALLOWED_IN_CUSTOMER_PORTAL
  • Trigger: Customer Portal の plan change で do_not_bill proration mode が使用された
  • Message: Customer Portal では do_not_bill proration mode は許可されていません
• DUPLICATE_ADDON_IDS_IN_REQUEST
  • Trigger: 同じ addon_id が request に複数回出現する
  • Message: 重複した addon IDs は許可されていません
• INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
  • Trigger: inactive subscription の plan change
  • Message: inactive subscription では plans の変更はサポートされていません
• INVALID_PRORATION_MODE_WITH_NEXT_BILLING_DATE
  • Trigger: effective_at: next_billing_date とともに full_immediately 以外の proration mode が使用された
  • Message: effective_at: next_billing_date では full_immediately proration mode のみ許可されます
• MISSING_ADDON_IDS
  • Trigger: addon_id list が空、または不明な IDs が含まれている
  • Message: 1 つ以上の product IDs が存在しません:
• ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
  • Trigger: on-demand では plan swap が許可されていない
  • Message: on demand subscriptions では plans の変更はサポートされていません
• ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Trigger: usage-based billing で on-demand を使用しようとした
  • Message: Usage Based Billing では On Demand Subscriptions はサポートされていません
• ONE_TIME_PRODUCTS_NOT_ALLOWED_FOR_ON_DEMAND
  • Trigger: on-demand subscription に one-time product が追加された
  • Message: on demand subscriptions では one-time products は許可されていません
• PENDING_PLAN_CHANGE_EXISTS
  • Trigger: 前の plan change が支払い待ちの間に、新しい plan change がリクエストされた
  • Message: この subscription には保留中の plan change がすでに存在します。現在の payment が完了するまでお待ちください。
• PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Trigger: business が無効にしている間に Customer Portal 経由で plan change を実行しようとした
  • Message: customer portal での Subscription plan change は無効です。
• PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Trigger: キャンセル予定の subscription で plan change を試行した
  • Message: Subscription はキャンセル予定です
• SCHEDULE_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Trigger: business が無効にしている間に Customer Portal 経由で plan change をスケジュールしようとした
  • Message: この business では plan changes のスケジューリングは無効です。
• SCHEDULED_PLAN_CHANGE_EXISTS
  • Trigger: すでに存在する scheduled plan change を作成しようとした
  • Message: この subscription には scheduled plan change がすでに存在します。新しいものを作成する前に、既存の scheduled change をキャンセルしてください。
• SCHEDULED_PLAN_CHANGE_NOT_FOUND
  • Trigger: 存在しない scheduled plan change を参照またはキャンセルしようとした
  • Message: この subscription に scheduled plan change が見つかりません。
• SUBSCRIPTION_EXPIRED
  • Trigger: expires_at を過ぎて billing しようとした
  • Message: Subscription の有効期限が切れているため、新しい charges を作成できません
• SUBSCRIPTION_INACTIVE
  • Trigger: Status ≠ active
  • Message: Subscription は active ではありません
• SUBSCRIPTION_NOT_ON_DEMAND
  • Trigger: on-demand が想定されたが fixed interval だった
  • Message: Subscription はすでに on demand ではありません
• SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
  • Trigger: Subscription payment の retry 回数が最大試行回数を超えた
  • Message: この subscription の最大 retry limit である 10 回を超えました

​

Products, Cart & Brands

• BRAND_ALREADY_ARCHIVED
  • Trigger: すでにアーカイブ済みの brand をアーカイブしようとした
  • Message: Brand はすでにアーカイブされています
• BRAND_ARCHIVED
  • Trigger: アーカイブ済みの brand の更新、verification への送信、または新しい product、product collection、subscription の関連付けを行おうとした
  • Message: Brand はアーカイブ済みのため更新できません
• BRAND_ARCHIVE_TARGET_REQUIRED
  • Trigger: products、live subscriptions、または product collections を保持している brand を、move_products_to target なしでアーカイブしようとした
  • Message: Brand には 12 個の product(s) があります。move_products_to に target brand を設定して、これらのタグを付け替えてください。
• BRAND_MISMATCH
  • Trigger: Cart items が異なる brands に属している
  • Message: product cart 内のすべての items は同じ brand に属している必要があります
• BRAND_NOT_ENABLED
  • Trigger: Brand が無効または active ではない
  • Message: 指定された Brand は有効になっていません
• BRAND_SUBMISSION_NOT_ENABLED
  • Trigger: Brand verification resubmission feature が有効になっていない
  • Message: Brand verification resubmission は有効になっていません
• CANNOT_ARCHIVE_PRIMARY_BRAND
  • Trigger: brand ID が business ID である primary brand をアーカイブしようとした
  • Message: Primary brand はアーカイブできません
• FILE_IN_USE
  • Trigger: active entitlement grants から参照されている digital product file を削除しようとした
  • Message: Digital file は active grants から参照されています
• INVALID_BRAND_ARCHIVE_TARGET
  • Trigger: move_products_to が、アーカイブ対象の brand、アーカイブ済みの brand、または別の business の brand を指定している
  • Message: move_products_to は、この business に属し、アーカイブされていない brand である必要があります
• INVALID_SUGGESTED_PRICE
  • Trigger: PWYW price < minimum allowed price
  • Message: Suggested Price は minimum price より低くできません。pay what you want の場合、price は最低受け入れ額として扱われます
• LOCALIZED_PRICE_ALREADY_EXISTS
  • Trigger: この product と country/currency に対する localized price がすでに存在する
  • Message: この product と country/currency に対する localized price はすでに存在します
• LOCALIZED_PRICE_DUPLICATES_BASE
  • Trigger: Localized price が product の base currency/country と重複している
  • Message: Localized price が product の base currency/country と重複しています
• LOCALIZED_PRICE_SHAPE_MISMATCH
  • Trigger: Localized price の shape が product の pricing_mode と一致しない
  • Message: Localized price の shape が product の pricing_mode と一致しません
• MISSING_PRODUCT_INFORMATION
  • Trigger: Product は存在するが、必須情報が不足している
  • Message: Product は存在しますが、その他の必須情報が不足しているか無効です
• PAY_AS_YOU_WANT_AMOUNT_REQUIRED
  • Trigger: PWYW product の price が不足している
  • Message: pay as you want product では Amount が必須です
• PRODUCT_CART_EMTPY
  • Trigger: 空の product cart が送信された
  • Message: product_cart は空です（error code は、API が返す正確な値 EMTPY と一致させるため、意図的にこの綴りになっています）
• PRODUCT_COLLECTION_IS_DELETED
  • Trigger: 削除された product collection を操作しようとした
  • Message: メッセージなし
• PRODUCT_COLLECTION_MUST_HAVE_PRODUCTS
  • Trigger: collection から最後の product（または product を含む最後の group）を削除しようとした
  • Message: collection の最後の product は削除できません。代わりに collection をアーカイブしてください。
• PRODUCT_IS_DELETED
  • Trigger: Product が soft-delete された
  • Message: メッセージなし
• PRODUCT_PRICING_MODE_REQUIRED
  • Trigger: product の pricing_mode が設定される前に localized prices を追加しようとした
  • Message: localized prices を追加する前に、Product の pricing_mode を設定する必要があります
• SLUG_ALREADY_TAKEN
  • Trigger: リクエストされた product slug / short URL がすでに使用されている
  • Message: Slug はすでに使用されています
• UNABLE_TO_EDIT_PRIMARY_BRAND
  • Trigger: 通常の API 経由で primary brand を更新しようとした
  • Message: Primary brand はこの API endpoint 経由では更新できません。

​

Discounts

• DISCOUNT_ALREADY_USED_ON_SUBSCRIPTION
  • Trigger: この subscription ですでに使用された discount を再適用しようとした
  • Message: この discount はこの subscription ですでに使用されています
• DISCOUNT_CODE_ALREADY_EXISTS
  • Trigger: 重複する discount code を作成しようとした
  • Message: Discount Code はすでに存在します
• DISCOUNT_CODE_EXPIRED
  • Trigger: expires_at date を過ぎた discount code
  • Message: Discount code の有効期限が切れています
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • Trigger: usage_limit に達した後に discount が再利用された
  • Message: Usage limit は times_used 未満にできません / Discount code は usage limit に達しました
  • Note: 終端状態 — code は使い切られています。再試行しないでください。
• DISCOUNT_CONCURRENT_REDEMPTION
  • Trigger: 同じ code の別の redemption が usage-limit row lock を長時間保持していた
  • Message: Discount は同時に利用されています。再試行してください
  • Note: 一時的なエラーです。code にはまだ利用可能回数が残っている可能性があるため、request は安全に再試行できます。顧客には「code を使い切った」と表示しないでください。
• DISCOUNT_CURRENCY_OPTION_INVALID
  • Trigger: create または update 時の無効な currency_options
  • Message: flat discount には、解決可能な default を持つ少なくとも 1 つの currency option が必要です / 重複する currency options は許可されていません / default としてマークできる currency option は 1 つだけです
• DISCOUNT_CUSTOMER_NOT_ELIGIBLE
  • Trigger: Customer が code の customer_eligibility（first_time、existing、または specific code の allow list に含まれていない）を満たしていない
  • Message: Customer はこの discount code の対象外です
• DISCOUNT_MINIMUM_SUBTOTAL_NOT_MET
  • Trigger: Cart subtotal が checkout currency に設定された minimum_subtotal を下回っている
  • Message: Cart subtotal が discount に必要な minimum required subtotal を下回っています
• DISCOUNT_NOT_YET_ACTIVE
  • Trigger: starts_at date より前に code が使用された
  • Message: Discount code はまだ active ではありません（starts_at が将来の日付です）
• DISCOUNT_PER_CUSTOMER_USAGE_LIMIT_EXCEEDED
  • Trigger: Customer がすでに code を per_customer_usage_limit 回引き換えている
  • Message: この discount code の customer ごとの usage limit を超えました
• DISCOUNT_NOT_APPLICABLE_TO_NEW_PRODUCT
  • Trigger: 既存の discount が適用されない product への plan change
  • Message: Discount は新しい plan の product に適用できません
• DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
  • Trigger: on-demand subscription に code が適用された
  • Message: Discount coupon は on demand subscriptions では利用できません
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • Trigger: 関係のない product(s) に code が適用された
  • Message: Discount coupon はこの product では利用できません
• INVALID_DISCOUNT_CODE
  • Trigger: Code が存在しない、または適用対象外
  • Message: Invalid Discount Code / Discount Code は cart 内のいずれの product にも適用できません
• INVALID_PERCENTAGE
  • Trigger: Percent amount > 100%（または 10,000 basis points）
  • Message: Percentage amount は 10000 を超えることができません / Discount code amount は 100% を超えることができません
• UNSUPPORTED_DISCOUNT_TYPE
  • Trigger: サポートされていない discount type。percentage と flat はどちらもサポートされていますが、per-unit amount discounts はサポートされていません。
  • Message: percentage と flat discount codes のみサポートされています

​

License Keys

• ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT
  • Trigger: License-key activations: new limit < existing instance count
  • Message: New activation limit は current instances count 未満にできません
• INACTIVE_LICENSE_KEY
  • Trigger: Key status ≠ active
  • Message: License key は active ではありません
• LICENSE_KEY_LIMIT_REACHED
  • Trigger: Activations = limit
  • Message: License key の activation limit に達しました
• LICENSE_KEY_NOT_FOUND
  • Trigger: Instance ID または key ID が無効
  • Message: License key instance が見つからないか、この license key に属していません
• NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
  • Trigger: sub-based key に expiry を設定しようとした
  • Message: subscription-based license key に expiry date は設定できません

​

Usage-Based Billing & Meters

• DUPLICATE_METER_IDS_IN_REQUEST
  • Trigger: 同じ meter ID が request に複数回出現する
  • Message: 重複する Meter Ids は許可されていません
• INVALID_QUANTITY
  • Trigger: usage-based pricing に無効な quantity が指定された
  • Message: usage based price products では quantity は 1 のみ許可されます
• METER_IS_DELETED
  • Trigger: 削除済みの meter を使用しようとした
  • Message: Meter はすでに削除されています
• MISSING_METER_IDS
  • Trigger: Meter ID list が空、または無効な IDs を含んでいる
  • Message: 1 つ以上の meter IDs が存在しません:

​

Credit-Based Billing

• CREDIT_ENTITLEMENT_IS_DELETED
  • Trigger: 削除された credit entitlement を操作しようとした
  • Message: Credit entitlement はすでに削除されています
• CREDIT_ENTITLEMENT_NAME_ALREADY_EXISTS
  • Trigger: すでに存在する name で credit entitlement を作成しようとした
  • Message: この name の credit entitlement はすでに存在します
• OVERAGE_LIMIT_EXCEEDED
  • Trigger: usage または credit deduction が設定された overage limit を超える
  • Message: Overage limit を超えました

​

Wallet

• INSUFFICIENT_WALLET_FUNDS
  • Trigger: Wallet balance < debit amount
  • Message: Wallet の funds が不足しています
• NEGATIVE_BALANCE_ADJUSTMENT
  • Trigger: Wallet balance を負の値にしようとした
  • Message: Wallet balance を負の値にすることはできません

​

Currency, Tax & Region

• EXCHANGE_RATE_NOT_FOUND
  • Trigger: from → to currency pair の FX rate がない
  • Message: Currency から Currency に変換するための Exchange rate が見つかりません
• INVALID_TAX_ID
  • Trigger: VAT/GST/TIN の validation に失敗した
  • Message: Tax Id が無効です
• REQUEST_AMOUNT_BELOW_MINIMUM
  • Trigger: Amount < product minimum
  • Message: Amount は product に指定された minimum amount 未満にできません
• TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
  • Trigger: Combined cart total < gateway minimum
  • Message: payment を処理するには 以上の minimum amount が必要です
• UNSUPPORTED_BILLING_CURRENCY
  • Trigger: リクエストされた billing currency はこの subscription ではサポートされていない
  • Message: subscriptions では USD 以外の billing currency はサポートされていません
• UNSUPPORTED_COUNTRY
  • Trigger: Geo がまだサポートされていない
  • Message: Country は現在サポートされていません
• UNSUPPORTED_CURRENCY
  • Trigger: Product または addon の currency が Dodo Payments で charge できる currency ではない。Base prices は charge 可能な任意の currency で設定できるため、通常は currency code が無効であるか、まだサポートされていないことを意味します。
  • Message: Currency は現在サポートされていません / 現在サポートされている product は USD と INR のみです / addon price でサポートされているのは USD と INR のみです / billing_currency に指定できるのは USD または INR のみです / Currency Not Supported / Indian card subscriptions では想定外の currency です
• UNSUPPORTED_TAX_CATEGORY
  • Trigger: Tax category string が enum に含まれていない
  • Message: Category は現在サポートされていません

​

Validation & Requests

• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • Trigger: 同じ item_id が items[] に 2 回出現する
  • Message: items array に重複した item_ids が指定されています
• INVALID_QUERY_PARAMS
  • Trigger: 相互排他的、または不正な query parameters
  • Message: Query params には time_frame または (start, end) のいずれか一方のみを含める必要があります
• INVALID_REQUEST_BODY
  • Trigger: 不正な JSON または schema violation
  • Message: Request body が無効です。request headers と object を確認してください。
• INVALID_REQUEST_PARAMETERS
  • Trigger: 意味的に誤っている（例: 過去の日付）
  • Message: next_billing_date を過去の時刻に変更できません
• MAXIMUM_KEYS_REACHED
  • Trigger: Metadata / custom-fields が 50 ペアを超えた
  • Message: 50 個の key-value pairs を超えています

​

General & System

• INTEGER_CONVERSION_FAILURE
  • Trigger: server-side で失敗する任意の integer ↔ string/decimal conversion
  • Message: Integer Conversion Failure
• INTERNAL_SERVER_ERROR
  • Trigger: 捕捉されない exceptions。server-side で詳細を log に記録してください
  • Message: 公開メッセージなし（generic 500）
• NOT_FOUND
  • Trigger: 欠落している任意の resource に対する generic 404
  • Message: Item が見つかりません (またはより具体的なメッセージ)
• TOO_MANY_REQUESTS
  • Trigger: 429 rate-limit
  • Message: メッセージなし
• UNSUPPORTED_ACTION
  • Trigger: resource type でサポートされていない action
  • Message: usage based subscriptions の plan change はサポートされていません

​

Best Practices

1. アプリケーションでは常にエラーを適切に処理してください
2. 適切な error logging を実装してください
3. エンドユーザーには適切なエラーメッセージを使用してください
4. 一時的なエラーに対する retry logic を実装してください
5. 解決しない問題については support にお問い合わせください

​

Support