Complete Error Response Guide for paymentMethod.proceed()

Overview

This document lists ALL possible error responses from paymentMethod.proceed() for Razorpay subscriptions, including complete JSON structures and when each error occurs.

Important Note: PaymentResult Structure

When payment gateway errors occur (e.g., payment.from_gateway), the error response includes a complete PaymentResult object with ALL attributes, even when they are null. This is because the backend serializes the entire PaymentResult object to JSON.

PaymentResult includes these fields:

success (boolean) - Always false for errors
payment_type (string) - Payment gateway type (e.g., "razorpay_recurring")
message (string) - Error message
payload (string) - Usually contains subscription ID or payment token
status (string null) - Gateway status (may be null, "authenticated", "failed", etc.)
code (string null) - Error code from gateway (may be null)
authorize_uri (string null) - Authorization URI (may be null or contain URI)
payment_token (string null)
amount_currency (string null)
amount_cents (number null)
transaction_id (string null)
international (boolean null)
skip_invoice (boolean null)
metadata (object null)
external_payment_id (string null)
external_capture_id (string null)
payment_gateway_fee (number null)
payment_gateway_fee_currency (string null)
external_refund_id (string null)
end_timestamp (string null)
client_payload (object null)

1. Client-Side Validation Errors (Before API Call)

These errors occur in the Razorpay provider before making any API calls.

1.1 Missing Plan Parameter

When: params.plan is missing or undefined

JSON Structure:

{
  "message": "SubscriptionParams.plan is required"
}

1.2 Missing Payment Parameter

When: params.payment is missing or undefined

JSON Structure:

{
  "message": "SubscriptionParams.payment is required"
}

1.3 Invalid Payment Type

When: params.payment.payment_type is not razorpay or razorpay_recurring

JSON Structure:

{
  "message": "Expected SubscriptionParams.payment.payment_type to be razorpay or razorpay_recurring"
}

2. Preview Subscription Errors (API Errors)

These errors occur during the previewSubscription API call (before opening Razorpay modal).

2.1 Server Error (500+)

When: Server returns status code >= 500 during preview API call

JSON Structure:

{
  "message": "preview_failed"
}

2.2 Invalid Subscription Parameters

Error Code: subscription_preview_invalid_subscription_params

When:

Subscriber identity is invalid
Payment type doesn’t match plan type (e.g., razorpay for recurring plan)
Amount currency doesn’t match subscription plan currency
Amount cents doesn’t match subscription plan amount
Subscription plan is not included in suitable plans for the asset
Dynamic assets are missing required fields (id, title, slug)
Coupon code is not accepted for this subscription plan
Coupon code cannot be applied on this payment type
Campaign target has been reached
Campaign has ended
Trial period is invalid (not available, duration exceeds plan limit, negative duration)

JSON Structure:

{
  "error": {
    "code": "subscription_preview_invalid_subscription_params",
    "message": {
      "subscriber": ["Subscriber identity is invalid"],
      "payment.payment_type": ["razorpay is not allowed for recurring plan"],
      "payment.amount_currency": ["INR does not match subscription plan currency USD"],
      "payment.amount_cents": ["10000 is not matching subscription plan amount 20000"],
      "payment.amount_cents": ["0 is not matching subscription plan amount 299900"],
      "subscription_plan": ["is not included in the list of suitable plans"],
      "dynamic_assets": ["are required"],
      "dynamic_assets": ["id is required"],
      "dynamic_assets": ["title is required"],
      "dynamic_assets": ["slug is required"],
      "coupon_code": ["not accepted for this subscription plan"],
      "coupon_code": ["can not be applied on this payment type"],
      "campaign_target": ["Campaign target reached"],
      "campaign_active": ["Campaign has ended"],
      "trial_period": ["Trial period available only for recurring subscription plans with trial enabled"],
      "trial_period.length": ["cannot have trial duration more than subscription plan trial duration"],
      "trial_period.unit": ["cannot have trial duration more than subscription plan trial duration"],
      "trial_period.length": ["trial duration should be positive"],
      "trial_period.unit": ["trial duration should be positive"]
    }
  }
}

2.3 Active Subscription Exists (Preview API)

Error Code: subscription_preview_active_subscription

When:

API Endpoint: /preview
Account Setting: allow_simultaneous_subscriptions? = true
Condition: Subscriber already has an active or pending recurring subscription for the same plan (same asset if applicable)
Validation: presence_of_similar_active_subscription during preview
Response Format: Controller uses special formatting with code and payload at top level

JSON Structure:

{
  "error": {
    "code": "subscription_preview_active_subscription",
    "message": [
      "already has active subscription for a recurring plan with same asset"
    ],
    "payload": {
      "subscription": {
        "id": 587652,
        "subscriber_id": 1921350,
        "subscription_plan_id": 6521,
        "start_timestamp": "2025-11-10T10:35:32.195Z",
        "end_timestamp": "2027-11-09T18:30:00.000Z",
        "plan_occurrence": "Recurring",
        "status": "active"
      }
    }
  }
}

Alternative Messages:

"already has active subscription for the same one time plan, can be repurchased after [date]"
"already has active subscription for a recurring plan"
"already has active subscription for the same asset"

2.4 Bad Attempt

Error Code: subscription_preview_bad_attempt

When: SubscriptionAttempt validation fails (e.g., attempt_token already taken)

JSON Structure:

{
  "error": {
    "code": "subscription_preview_bad_attempt",
    "message": {
      "attempt_token": ["has already been taken"]
    }
  }
}

2.5 Validation Failed (Payment Gateway Error)

Error Code: subscription_preview_validation_failed

When: Payment gateway validation fails during preview (e.g., Razorpay subscription not active/authenticated)

JSON Structure (Complete PaymentResult):

{
  "error": {
    "code": "subscription_preview_validation_failed",
    "message": {
      "payment.from_gateway": [
        {
          "payment_type": "razorpay_recurring",
          "success": false,
          "payload": "sub_RcpIvN6Hjx8KaW",
          "status": null,
          "code": null,
          "message": "Verification failed. Subscription neither active nor authenticated",
          "authorize_uri": null,
          "payment_token": null,
          "amount_currency": null,
          "amount_cents": null,
          "transaction_id": null,
          "international": null,
          "skip_invoice": null,
          "metadata": null,
          "external_payment_id": null,
          "external_capture_id": null,
          "payment_gateway_fee": null,
          "payment_gateway_fee_currency": null,
          "external_refund_id": null,
          "end_timestamp": null,
          "client_payload": null
        }
      ]
    }
  }
}

Common Messages:

"Verification failed. Subscription neither active nor authenticated"
"Subscription is not active"
"Subscription neither active or authenticated"

2.6 Active Secondary Subscription (Bundle)

Error Code: subscription_preview_active_secondary_subscription

When: Active subscription exists in other accounts for bundle subscription

JSON Structure:

{
  "error": {
    "code": "subscription_preview_active_secondary_subscription",
    "message": "Active subscription exists for other accounts"
  }
}

2.7 Campaign Ended

Error Code: subscription_preview_campaign_ended

When: Campaign has ended and user tries to subscribe

JSON Structure:

{
  "error": {
    "code": "subscription_preview_campaign_ended",
    "message": "Campaign has ended"
  }
}

2.8 Price Currency Invalid

Error Code: subscription_preview_invalid_subscription_params

When: Price currency invalid (currency for region doesn’t match allowed currency)

JSON Structure:

{
  "error": {
    "code": "subscription_preview_invalid_subscription_params",
    "message": "Price currency invalid"
  }
}

These errors occur when the user interacts with the Razorpay payment modal.

When: User clicks close/cancel on Razorpay modal

JSON Structure:

{
  "message": "user closed the payment"
}

3.2 Payment Incomplete

When: Payment completed but razorpay_payment_id is missing from response

JSON Structure:

{
  "message": "payment_incomplete"
}

4. Create Subscription Errors (After Payment)

These errors occur after payment is successful, during the createSubscription API call.

4.1 Server Error (500+)

When: Server returns status code >= 500 during create subscription API call

JSON Structure:

{
  "message": "purchase_failed"
}

4.2 Currency Mismatch

When: Payment amount currency doesn’t match subscription plan currency or subscription attempt currency

JSON Structure:

{
  "error": {
    "payment.amount_currency": ["INR does not match subscription plan currency USD"],
    "payment.amount_currency": ["USD does not match any configured subscription plan currencies"]
  }
}

Alternative (Create API):

{
  "error": {
    "message": "Price currency invalid. Subscription attempt currency: INR, request currency: USD"
  }
}

4.3 Amount Mismatch

When: Payment amount doesn’t match subscription plan amount

JSON Structure:

{
  "error": {
    "payment.amount_cents": ["10000 is not matching subscription plan amount 20000"],
    "payment.amount_cents": ["0 is not matching subscription plan amount 299900"]
  }
}

When This Occurs:

Sending 0 amount for a paid plan
Sending incorrect amount
Currency mismatch causing amount conversion issues
Free trial logic sending 0 when plan requires payment

Note: Validation is skipped if:

account.skip_price_validation is true
payment.skip_price_validation is true
Payment type is in SKIP_PRICE_VALIDATION_PAYMENT_TYPES (manual, androidpay, googlepay, applepay, bundle)

4.4 Payment Type Mismatch

When: Payment type doesn’t match plan type

JSON Structure:

{
  "error": {
    "payment.payment_type": ["razorpay is not allowed for recurring plan"],
    "payment.payment_type": ["razorpay_recurring is not allowed for one time plan"],
    "payment.payment_type": ["manual is allowed only for zero priced plans"]
  }
}

4.5 Payment Gateway Error

When: Payment gateway verification fails (e.g., Razorpay subscription not active/authenticated, payment gateway error)

JSON Structure (Complete PaymentResult):

{
  "error": {
    "payment.from_gateway": [
      {
        "payment_type": "razorpay_recurring",
        "success": false,
        "payload": "sub_RcpIvN6Hjx8KaW",
        "status": null,
        "code": null,
        "message": "Verification failed. Subscription neither active nor authenticated",
        "authorize_uri": null,
        "payment_token": null,
        "amount_currency": null,
        "amount_cents": null,
        "transaction_id": null,
        "international": null,
        "skip_invoice": null,
        "metadata": null,
        "external_payment_id": null,
        "external_capture_id": null,
        "payment_gateway_fee": null,
        "payment_gateway_fee_currency": null,
        "external_refund_id": null,
        "end_timestamp": null,
        "client_payload": null
      }
    ]
  }
}

Common Messages:

"Verification failed. Subscription neither active nor authenticated"
"Subscription is not active"
"Subscription neither active or authenticated"

When This Occurs:

Payment deducted but Razorpay subscription status is “authenticated” (not “active”) yet
Payment gateway verification fails
Subscription status doesn’t meet activation requirements

4.6 Duplicate Payment Token

When: Payment token already exists in the system

JSON Structure:

{
  "error": {
    "payment.payment_token": ["duplicate payment token sub_1234567890"]
  }
}

4.7 Missing Payment Token

When: Payment token is required but missing

JSON Structure:

{
  "error": {
    "payment.payment_token": ["can't be blank"]
  }
}

4.8 Active Subscription Exists (Create API)

When:

API Endpoint: /create
Account Setting: allow_simultaneous_subscriptions? = false OR one-time plan blocking enabled
Condition: Subscriber already has an active or pending subscription
Validation: presence_of_similar_active_subscription during create
Response Format: Controller uses render_validation_error which renders ActiveModel errors directly

JSON Structure:

{
  "error": {
    "subscriber": [
      "already has active subscription for a recurring plan",
      "already has active subscription for the same asset",
      "already has active subscription for the same one time plan, can be repurchased after 15 Jan 2024"
    ],
    "code": [
      "subscription_preview_active_subscription"
    ],
    "subscription": {
      "id": 587652,
      "subscriber_id": 1921350,
      "subscription_plan_id": 6521,
      "start_timestamp": "2025-11-10T10:35:32.195Z",
      "end_timestamp": "2027-11-10T10:35:32.195Z",
      "plan_occurrence": "Recurring"
    }
  }
}

When This Occurs:

allow_simultaneous_subscriptions? = false and subscriber has active recurring subscription
block_identical_simultaneous_ot_subs = true and subscriber has active one-time subscription for same plan
Pay-per-asset subscription and subscriber has active subscription for same asset
allow_simultaneous_subscriptions? = true and subscriber has active recurring subscription with same asset

4.9 Invalid Subscription Attempt Token

When: Subscription attempt token doesn’t exist or is invalid

JSON Structure:

{
  "error": {
    "message": "Did not find subscription attempt for attempt token abc123xyz"
  }
}

4.10 Payment Invoice Error

When: Invoice validation fails

JSON Structure:

{
  "error": {
    "payment.payment_invoice": ["Invoice validation error messages"]
  }
}

4.11 Subscription Gift Error

When: Subscriber and gifter are the same person

JSON Structure:

{
  "error": {
    "subscription_gift": ["subscriber cannot be same as gifter"]
  }
}

4.12 Invalid Subscriber Identity

When: Subscriber identity is invalid

JSON Structure:

{
  "error": {
    "subscriber": ["Subscriber identity is invalid"]
  }
}

4.13 Subscription Plan Error

When: Subscription plan is not included in suitable plans for the asset

JSON Structure:

{
  "error": {
    "subscription_plan": ["is not included in the list of suitable plans"]
  }
}

5. HTTP Status Code Errors

5.1 403 Forbidden

When: User doesn’t have permission (e.g., trying to create manual subscription without superuser privileges)

JSON Structure:

{
  "error": {
    "message": "Cannot create manual payment"
  }
}

Other 403 Errors:

{
  "error": {
    "message": "Cannot create subscription with fixed start time"
  }
}

{
  "error": {
    "message": "Cannot extend subscription"
  }
}

5.2 404 Not Found

When: Resource not found

JSON Structure:

{
  "error": {
    "message": "Unknown value for subscription_type"
  }
}

{
  "error": {
    "message": "SubscriptionPlan not found"
  }
}

{
  "error": {
    "message": "Subscription not found"
  }
}

5.3 422 Unprocessable Entity

When: Validation fails (most common) - See sections 2.2 and 4.2 for detailed structures

5.4 401 Unauthorized

When: Authentication fails (missing/invalid API key)

JSON Structure:

{
  "error": {
    "message": "Unauthorized"
  }
}

5.5 500 Internal Server Error

When: Server error

JSON Structure:

{
  "message": "preview_failed"
}

{
  "message": "purchase_failed"
}

6. Payment Gateway Specific Errors

6.1 Razorpay Recurring - Subscription Not Active

When: Payment deducted but subscription status is “authenticated” (not “active”) or verification fails

JSON Structure (Complete PaymentResult):

{
  "error": {
    "payment.from_gateway": [
      {
        "payment_type": "razorpay_recurring",
        "success": false,
        "payload": "sub_RcpIvN6Hjx8KaW",
        "status": null,
        "code": null,
        "message": "Verification failed. Subscription neither active nor authenticated",
        "authorize_uri": null,
        "payment_token": null,
        "amount_currency": null,
        "amount_cents": null,
        "transaction_id": null,
        "international": null,
        "skip_invoice": null,
        "metadata": null,
        "external_payment_id": null,
        "external_capture_id": null,
        "payment_gateway_fee": null,
        "payment_gateway_fee_currency": null,
        "external_refund_id": null,
        "end_timestamp": null,
        "client_payload": null
      }
    ]
  }
}

Alternative Message Examples:

{
  "error": {
    "payment.from_gateway": [
      {
        "payment_type": "razorpay_recurring",
        "success": false,
        "payload": "sub_1234567890",
        "status": "authenticated",
        "code": null,
        "message": "Subscription is not active",
        "authorize_uri": null
      }
    ]
  }
}

{
  "error": {
    "payment.from_gateway": [
      {
        "payment_type": "razorpay_recurring",
        "success": false,
        "payload": "sub_1234567890",
        "status": null,
        "code": null,
        "message": "Subscription neither active or authenticated",
        "authorize_uri": null
      }
    ]
  }
}

Common Messages:

"Verification failed. Subscription neither active nor authenticated"
"Subscription is not active"
"Subscription neither active or authenticated"

When This Occurs:

Payment is successfully deducted from user’s account
Razorpay subscription status is still “authenticated” (pending activation)
Backend validates subscription status with Razorpay API
Validation fails because subscription isn’t “active” yet
proceed() Promise rejects with error

6.2 Payment Gateway Not Enabled

When: Payment gateway is not enabled by admin

JSON Structure:

{
  "error": {
    "message": "Payment gateway not enabled by admin"
  }
}

7. Error Code Reference

Client-Side Errors

missing_plan - SubscriptionParams.plan is required
missing_payment - SubscriptionParams.payment is required
invalid_payment_type - Invalid payment_type value

User Action Errors

payment_cancelled - User closed the payment modal
payment_incomplete - Payment incomplete (missing payment_id)

Server Errors

preview_failed - Preview API call failed (500+)
purchase_failed - Create subscription API call failed (500+)

API Error Codes

subscription_preview_invalid_subscription_params - Invalid subscription parameters
subscription_preview_active_subscription - Active subscription exists
subscription_preview_bad_attempt - Invalid subscription attempt
subscription_preview_validation_failed - Validation failed (payment gateway error)
subscription_preview_active_secondary_subscription - Active subscription in other accounts (bundle)
subscription_preview_campaign_ended - Campaign has ended
initiate_subscription_validation_failed - Initiate subscription validation failed

HTTP Status Codes

401 - Unauthorized
403 - Forbidden
404 - Not Found
422 - Unprocessable Entity (validation errors)
500 - Internal Server Error

8. Field-Specific Error Messages

Subscriber Errors

"Subscriber identity is invalid"
"already has active subscription for a recurring plan"
"already has active subscription for a recurring plan with same asset"
"already has active subscription for the same asset"
"already has active subscription for the same one time plan, can be repurchased after [date]"

Payment Errors

"razorpay is not allowed for recurring plan"
"razorpay_recurring is not allowed for one time plan"
"manual is allowed only for zero priced plans"
"INR does not match subscription plan currency USD"
"10000 is not matching subscription plan amount 20000"
"0 is not matching subscription plan amount 299900"
"can't be blank" (payment_token)
"duplicate payment token [token]"
"Verification failed. Subscription neither active nor authenticated" (gateway error)
"Subscription is not active" (gateway error)
"Subscription neither active or authenticated" (gateway error)

Subscription Plan Errors

"is not included in the list of suitable plans"

Coupon Code Errors

"not accepted for this subscription plan"
"can not be applied on this payment type"

Campaign Errors

"Campaign target reached"
"Campaign has ended"

Trial Period Errors

"Trial period available only for recurring subscription plans with trial enabled"
"cannot have trial duration more than subscription plan trial duration"
"trial duration should be positive"

Dynamic Assets Errors

"are required"
"id is required"
"title is required"
"slug is required"

Subscription Gift Errors

"subscriber cannot be same as gifter"

9. Summary: When Errors Occur

Preview API Errors

Invalid Parameters: Missing/invalid subscriber, payment type mismatch, amount/currency mismatch, invalid plan, missing assets, invalid coupon, campaign ended
Active Subscription: Subscriber already has active subscription (when allow_simultaneous_subscriptions? = true)
Payment Gateway Error: Gateway validation fails (subscription not active/authenticated)
Server Error: HTTP 500+ response

Create API Errors

Invalid Parameters: Same as preview, plus currency/amount mismatch with attempt token
Active Subscription: Subscriber already has active subscription (when allow_simultaneous_subscriptions? = false or one-time plan blocking)
Payment Gateway Error: Gateway verification fails after payment
Missing Token: Payment token missing or invalid
Duplicate Token: Payment token already exists
Server Error: HTTP 500+ response

User Action Errors

User Cancelled: User closes Razorpay modal
Payment Incomplete: Payment completed but payment_id missing

HTTP Status Errors

401: Unauthorized (missing/invalid API key)
403: Forbidden (insufficient permissions)
404: Not Found (resource doesn’t exist)
422: Unprocessable Entity (validation errors)
500: Internal Server Error

Complete Error Response Guide for paymentMethod.proceed()

Overview

Important Note: PaymentResult Structure

1. Client-Side Validation Errors (Before API Call)

1.1 Missing Plan Parameter

1.2 Missing Payment Parameter

1.3 Invalid Payment Type

2. Preview Subscription Errors (API Errors)

2.1 Server Error (500+)

2.2 Invalid Subscription Parameters

2.3 Active Subscription Exists (Preview API)

2.4 Bad Attempt

2.5 Validation Failed (Payment Gateway Error)

2.6 Active Secondary Subscription (Bundle)

2.7 Campaign Ended

2.8 Price Currency Invalid

3. Razorpay Modal Errors (User Action)

3.1 User Closes Modal

3.2 Payment Incomplete

4. Create Subscription Errors (After Payment)

4.1 Server Error (500+)

4.2 Currency Mismatch

4.3 Amount Mismatch

4.4 Payment Type Mismatch

4.5 Payment Gateway Error

4.6 Duplicate Payment Token

4.7 Missing Payment Token

4.8 Active Subscription Exists (Create API)

4.9 Invalid Subscription Attempt Token

4.10 Payment Invoice Error

4.11 Subscription Gift Error

4.12 Invalid Subscriber Identity

4.13 Subscription Plan Error

5. HTTP Status Code Errors

5.1 403 Forbidden

5.2 404 Not Found

5.3 422 Unprocessable Entity

5.4 401 Unauthorized

5.5 500 Internal Server Error

6. Payment Gateway Specific Errors

6.1 Razorpay Recurring - Subscription Not Active

6.2 Payment Gateway Not Enabled

7. Error Code Reference

Client-Side Errors

User Action Errors

Server Errors

API Error Codes

HTTP Status Codes

8. Field-Specific Error Messages

Subscriber Errors

Payment Errors

Subscription Plan Errors

Coupon Code Errors

Campaign Errors

Trial Period Errors

Dynamic Assets Errors

Subscription Gift Errors

9. Summary: When Errors Occur

Preview API Errors

Create API Errors

User Action Errors

HTTP Status Errors