Error Handling

Available in🇮🇳 India

Read error.code, reason, source and step. Do not retry BAD_REQUEST_ERROR; retry SERVER_ERROR with back-off. Show the customer description, but branch your logic on reason and source. Test it: trigger each failure with the reserved amounts on your method pages and confirm you branch correctly — incorrect_pin → retry, insufficient_funds → use another account, bank errors → retry later.

`error.code`	Meaning	Do this
`BAD_REQUEST_ERROR`	Something in the request or the customer’s input	Do not retry as-is. Fix the request, or ask the customer to try again or use another method.
`GATEWAY_ERROR`	The bank or network failed	Offer another method. Check downtimes.
`SERVER_ERROR`	Razorpay failed	Retry with back-off, following Retries and Idempotency.

Show the customer description. Log reason, source and step for support and dashboards. Group failures by reason to spot a bank or method that is failing.

Behaviour	Live mode	Test mode
Payment failures	Real failures	Triggered with each method’s failure triggers
Request errors	Real	Same validation: send the bad request (Orders)
Server errors (5xx)	Rare	Cannot be triggered

Scenarios to test your integration

Scenario ID	Area	Scenario	Trigger	Steps to follow	Test mode
BP-13	`BAD_REQUEST_ERROR`	Do not retry a bad request as-is	A bad order request (ORD-08); a customer failure trigger (card `4100 2800 0005 0004`, UPI `402`)	Trigger each. Confirm no automatic retry: fix the request, or ask the customer to retry or use another method.	Available
BP-32	`GATEWAY_ERROR`	Offer another method on a bank or network failure	Card `4100 2800 0002 0007`, UPI `101`	Trigger each. Confirm you offer another method and check downtimes.	Available
BP-33	`SERVER_ERROR`	Retry Razorpay failures with back-off	—	Confirm `5xx` responses are retried with back-off, following Retries and Idempotency.	Live only
BP-34	Messaging	Show `description`, log the rest	Any failure trigger	Confirm the customer sees `description`. Confirm `reason`, `source` and `step` are logged.	Available
BP-35	Monitoring	Spot a failing bank or method	Several failure triggers	Confirm your dashboards group failures by `reason`.	Available

Common integration gaps to avoid

Gap	What goes wrong in production	What to do	Test with
Retrying bad requests	The same `BAD_REQUEST_ERROR` fails again and again.	Fix the request; retry only `SERVER_ERROR`.	BP-13
Matching on `description`	A wording change breaks your handling.	Branch on `reason` and `source`.	BP-34
No per-reason monitoring	A failing bank goes unnoticed for hours.	Dashboard failures by `reason`.	BP-35

Simulate failures by method

Each method page lists the errors you can trigger in Test Mode, with the trigger for each, and the ones you cannot. Run every available error through your handling and check: no blind retry, the right next step for the customer, description shown, and reason/source/step logged.

Method	How you trigger an error	Available in test mode	Not available in test mode
Orders	Request errors on `POST /v1/orders`	7 reasons	8 reasons
Cards	Test card + failure on the mock bank page	31 reasons	38 reasons
UPI Intent	Amount in paise	20 reasons	30 reasons
UPI QR	Amount in paise (Intent amounts)	20 reasons	30 reasons
UPI Collect	`failure@razorpay` + amount	6 reasons	26 reasons
Card recurring	Registration or debit card	16 reasons	35 reasons
UPI Autopay Intent	Amount on the order and payment	27 reasons	52 reasons
UPI Autopay QR	Amount on the order and payment	27 reasons	52 reasons
UPI Autopay Collect	Amount on the order and payment	27 reasons	52 reasons

Available in test mode

Failure	How to simulate	Expected handling	Scenario
Customer failure	Method failure triggers	Message, no auto-retry	BP-13
Gateway failure	Card `4100 2800 0002 0007`, UPI `101`	Offer another method	BP-32

Not available in test mode

Failure	Why not	How to cover it
Razorpay 5xx	Cannot be triggered	Retry with back-off (BP-33)

1. Build Integration

2. Test S2S Integration

3. Go Live Checklist

Features

Scenarios to test your integration

Common integration gaps to avoid

Simulate failures by method

Scenarios to test your integration

Common integration gaps to avoid

Simulate failures by method

Related Information