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

# Error Handling

> Branch on error.code, reason and source, with the scenarios, gaps and failures to test for each method.

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](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/retries-and-idempotency.md). |

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](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md)) |
| 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) |

### Related Information

* [Best Practices](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices)
* [Retries and Idempotency](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices/retries-and-idempotency.md)
* [Orders](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md)