> ## Documentation Index
> Fetch the complete documentation index at: https://better-auth-razorpay.amankushwaha.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Error codes

> Complete reference of error codes thrown by the plugin, grouped by feature area, with meaning and the endpoints that raise them.

The plugin throws errors via the Better Auth API error system. On the client, each error has a `code` and `message` you can inspect to handle failures gracefully.

## Importing error codes

The server entry and client entry both re-export `RAZORPAY_ERROR_CODES`.

```ts theme={null}
import { RAZORPAY_ERROR_CODES } from "@amank-root/better-auth-razorpay";
// or from the client entry
import { RAZORPAY_ERROR_CODES } from "@amank-root/better-auth-razorpay/client";
```

## Checking error codes

Compare the error code directly in your client or server code.

```ts theme={null}
const { data, error } = await authClient.razorpay.createOrder({
  amount: 50000,
  currency: "INR",
});

if (error?.code === "INVALID_ORDER_AMOUNT") {
  console.log("Amount must be at least 100 paise for INR.");
}

if (error?.code === "ALREADY_SUBSCRIBED_PLAN") {
  console.log("You are already subscribed to this plan.");
}
```

## General errors

| Code | Meaning | Raised by |
| - | - | - |
| `UNAUTHORIZED` | Unauthorized access. | Any endpoint when authorization fails |
| `INVALID_REQUEST_BODY` | The request body failed validation. | Any endpoint with body validation |
| `EMAIL_VERIFICATION_REQUIRED` | Email must be verified before subscribing. | `upgradeSubscription` when `requireEmailVerification` is true |
| `CUSTOMER_NOT_FOUND` | Razorpay customer not found for this user. | `upgradeSubscription` and related customer-dependent flows |
| `UNABLE_TO_CREATE_CUSTOMER` | Failed to create a Razorpay customer. | Customer creation flows |
| `AUTHORIZE_REFERENCE_REQUIRED` | `authorizeReference` is required for organization subscriptions. | Organization subscription endpoints |
| `REFERENCE_ID_NOT_ALLOWED` | The provided reference ID is not allowed. | `authorizeReference` returning false |
| `ORGANIZATION_NOT_FOUND` | Organization not found. | Organization customer flows |
| `ORGANIZATION_SUBSCRIPTION_NOT_ENABLED` | Organization subscriptions are not enabled. | Organization subscription endpoints |
| `ORGANIZATION_HAS_ACTIVE_SUBSCRIPTION` | Cannot delete an organization with an active subscription. | Organization deletion hooks |
| `ORGANIZATION_REFERENCE_ID_REQUIRED` | Reference ID is required for organization subscriptions. | `upgradeSubscription` when no reference ID is resolved |

## Payment and order errors

| Code | Meaning | Raised by |
| - | - | - |
| `INVALID_PAYMENT_SIGNATURE` | The Razorpay payment signature is invalid. | `verifyRazorpayPayment` |
| `INVALID_ORDER_AMOUNT` | Order amount is invalid (minimum 100 paise for INR). | `createRazorpayOrder` |
| `INVALID_PARTIAL_PAYMENT` | `firstPaymentMinAmount` requires `partialPayment` to be true. | `createRazorpayOrder` |
| `PAYMENT_FETCH_FAILED` | Failed to fetch payment details from Razorpay. | `verifyRazorpayPayment` |
| `PAYMENT_NOT_CAPTURED` | Payment has not been captured yet. | Verification flows |
| `PAYMENT_AMOUNT_MISMATCH` | Payment amount does not match expected amount. | Verification flows |
| `PAYMENT_ORDER_MISMATCH` | Payment order ID does not match expected order. | Verification flows |
| `ORDER_FETCH_FAILED` | Failed to fetch order details. | `getRazorpayOrder` |
| `ORDER_LIST_FAILED` | Failed to list orders. | `fetchAllOrders` |
| `ORDER_EDIT_FAILED` | Failed to edit order notes. | `editOrder` |
| `ORDER_PAYMENTS_FETCH_FAILED` | Failed to fetch payments for an order. | `fetchPaymentsForOrder` |

## Refund errors

| Code | Meaning | Raised by |
| - | - | - |
| `REFUND_NOT_FOUND` | The requested refund was not found. | `fetchRefund` |
| `REFUND_FETCH_FAILED` | Failed to fetch refund details. | Refund fetch operations |
| `REFUND_LIST_FAILED` | Failed to list refunds. | `fetchAllRefunds` |
| `REFUND_EDIT_FAILED` | Failed to edit refund notes. | `editRefund` |

## Subscription errors

| Code | Meaning | Raised by |
| - | - | - |
| `SUBSCRIPTION_NOT_FOUND` | Subscription not found. | `cancelSubscription`, `pauseSubscription`, `resumeSubscription`, `updateSubscription`, `restoreSubscription`, `getSubscription` |
| `SUBSCRIPTION_PLAN_NOT_FOUND` | The requested plan was not found in the configured plans. | `upgradeSubscription` |
| `ALREADY_SUBSCRIBED_PLAN` | You are already subscribed to this plan. | `upgradeSubscription` when already active on the same plan |
| `SUBSCRIPTION_NOT_ACTIVE` | Subscription is not in an active state. | `pauseSubscription` |
| `SUBSCRIPTION_ALREADY_CANCELLED` | Subscription has already been cancelled. | `cancelSubscription` |
| `SUBSCRIPTION_ALREADY_PAUSED` | Subscription is already paused. | `pauseSubscription` |
| `SUBSCRIPTION_NOT_PAUSED` | Subscription is not paused. | `resumeSubscription` |
| `SUBSCRIPTION_NOT_PENDING_CANCEL` | Subscription is not scheduled to cancel at cycle end. | `restoreSubscription` |
| `SUBSCRIPTION_CANCEL_FAILED` | Failed to cancel the subscription. | `cancelSubscription` |
| `SUBSCRIPTION_PAUSE_FAILED` | Failed to pause the subscription. | `pauseSubscription` |
| `SUBSCRIPTION_RESUME_FAILED` | Failed to resume the subscription. | `resumeSubscription` |
| `SUBSCRIPTION_UPDATE_FAILED` | Failed to update the subscription. | `updateSubscription`, `upgradeSubscription` |
| `SUBSCRIPTION_RESTORE_FAILED` | Failed to restore the subscription. | `restoreSubscription` |
| `SUBSCRIPTION_RENEW_FAILED` | Failed to renew the subscription. | Renewal flows |
| `SUBSCRIPTION_LIST_FAILED` | Failed to list subscriptions. | `listSubscriptions` |
| `FAILED_TO_FETCH_PLANS` | Failed to fetch subscription plans. | `upgradeSubscription` when plans resolver fails |
| `TRIAL_ALREADY_USED` | Free trial has already been used for this reference. | `upgradeSubscription` when a previous subscription already had a trial |

## Subscription link and offer errors

| Code | Meaning | Raised by |
| - | - | - |
| `SUBSCRIPTION_LINK_CREATE_FAILED` | Failed to create a subscription link. | `createSubscriptionLink` |
| `SUBSCRIPTION_INVOICE_FETCH_FAILED` | Failed to fetch subscription invoices. | `fetchInvoices` |
| `PENDING_UPDATE_NOT_FOUND` | No pending update found for this subscription. | `fetchPendingUpdate` |
| `PENDING_UPDATE_CANCEL_FAILED` | Failed to cancel the pending update. | `cancelPendingUpdate` |
| `OFFER_LINK_FAILED` | Failed to link offer to subscription. | `linkOffer` |
| `OFFER_DELETE_FAILED` | Failed to delete offer from subscription. | `deleteOffer` |
| `ADDON_CREATE_FAILED` | Failed to create subscription add-on. | `createSubscriptionAddon` |

## Plan errors

| Code | Meaning | Raised by |
| - | - | - |
| `PLAN_NOT_FOUND` | The requested plan was not found. | `fetchPlan` |
| `PLAN_CREATE_FAILED` | Failed to create a plan. | `createPlan` |

## Invoice errors

| Code | Meaning | Raised by |
| - | - | - |
| `INVOICE_NOT_FOUND` | The requested invoice was not found. | `fetchInvoice` |
| `INVOICE_CREATE_FAILED` | Failed to create an invoice. | `createInvoice` |
| `INVOICE_FETCH_FAILED` | Failed to fetch invoice details. | `fetchInvoice` |
| `INVOICE_LIST_FAILED` | Failed to list invoices. | `fetchAllInvoices` |
| `INVOICE_EDIT_FAILED` | Failed to edit the invoice. | `editInvoice` |
| `INVOICE_ISSUE_FAILED` | Failed to issue the invoice. | `issueInvoice` |
| `INVOICE_DELETE_FAILED` | Failed to delete the invoice. | `deleteInvoice` |
| `INVOICE_CANCEL_FAILED` | Failed to cancel the invoice. | `cancelInvoice` |
| `INVOICE_NOTIFY_FAILED` | Failed to notify by invoice. | `notifyByInvoice` |

## Customer errors

| Code | Meaning | Raised by |
| - | - | - |
| `CUSTOMER_EDIT_FAILED` | Failed to edit customer details. | `editCustomer` |
| `BANK_ACCOUNT_ADD_FAILED` | Failed to add bank account to customer. | `addBankAccount` |
| `BANK_ACCOUNT_DELETE_FAILED` | Failed to delete bank account. | `deleteBankAccount` |
| `TOKEN_FETCH_FAILED` | Failed to fetch customer tokens. | `fetchTokens` |
| `TOKEN_DELETE_FAILED` | Failed to delete customer token. | `deleteToken` |

## Add-on and item errors

| Code | Meaning | Raised by |
| - | - | - |
| `ADDON_NOT_FOUND` | The requested add-on was not found. | `fetchAddon` |
| `ADDON_FETCH_FAILED` | Failed to fetch add-on details. | `fetchAddon` |
| `ADDON_LIST_FAILED` | Failed to list add-ons. | `listAddons` |
| `ADDON_DELETE_FAILED` | Failed to delete the add-on. | `deleteAddon` |
| `ITEM_NOT_FOUND` | The requested item was not found. | `fetchItem` |
| `ITEM_CREATE_FAILED` | Failed to create an item. | `createItem` |
| `ITEM_FETCH_FAILED` | Failed to fetch item details. | `fetchItem` |
| `ITEM_LIST_FAILED` | Failed to list items. | `listItems` |
| `ITEM_EDIT_FAILED` | Failed to edit the item. | `editItem` |
| `ITEM_DELETE_FAILED` | Failed to delete the item. | `deleteItem` |

## Transfer errors

| Code | Meaning | Raised by |
| - | - | - |
| `TRANSFER_CREATE_FAILED` | Failed to create a transfer. | `createRazorpayTransfer` |
| `TRANSFER_FETCH_FAILED` | Failed to fetch transfer details. | `getRazorpayTransfer` |
| `TRANSFER_LIST_FAILED` | Failed to list transfers. | `listRazorpayTransfers` |
| `TRANSFER_EDIT_FAILED` | Failed to edit the transfer. | `editRazorpayTransfer` |
| `TRANSFER_REVERSE_FAILED` | Failed to reverse the transfer. | `reverseRazorpayTransfer` |

## Webhook errors

| Code | Meaning | Raised by |
| - | - | - |
| `WEBHOOK_SIGNATURE_NOT_FOUND` | The `x-razorpay-signature` header is missing. | Webhook endpoint |
| `WEBHOOK_SECRET_NOT_FOUND` | `razorpayWebhookSecret` is not configured. | Webhook endpoint |
| `FAILED_TO_VERIFY_WEBHOOK` | Webhook signature verification failed. | Webhook endpoint |
| `WEBHOOK_ERROR` | An error occurred while handling the webhook. | Webhook endpoint |

## Handling errors in React

When using TanStack Query hooks, errors surface through the mutation or query error state.

```tsx theme={null}
import { useUpgradeSubscription } from "@amank-root/better-auth-razorpay/react";

function UpgradeButton() {
  const mutation = useUpgradeSubscription(authClient);

  return (
    <button
      onClick={async () => {
        try {
          await mutation.mutateAsync({ plan: "pro" });
        } catch (err: any) {
          if (err?.code === "ALREADY_SUBSCRIBED_PLAN") {
            alert("You are already on the Pro plan.");
          } else if (err?.code === "CUSTOMER_NOT_FOUND") {
            alert("Please complete your profile first.");
          }
        }
      }}
    >
      Upgrade to Pro
    </button>
  );
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.