code and message you can inspect to handle failures gracefully.
Importing error codes
The server entry and client entry both re-exportRAZORPAY_ERROR_CODES.
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.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.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>
);
}