# Errors & troubleshooting

## Authentication errors (`401`)

| Message | Resolution |
| --- | --- |
| `Unauthorized - Missing API Key` | Add `Authorization: Bearer YOUR_API_KEY` |
| `Unauthorized - Invalid API Key` | Copy the current key from the merchant dashboard and remove extra spaces |
| `Unauthorized - Merchant is not approved` | Complete merchant approval or contact support |
| `Unauthorized - IP not whitelisted` | Add the server egress IP to the whitelist |

## Deposit validation errors

| Message | Resolution |
| --- | --- |
| `amount: Amount must be at least 100` | Increase the deposit amount to at least INR 100 |
| `amount: Amount must not exceed 50000` | Reduce the deposit amount to INR 50,000 or less |
| `webhook_url: Invalid webhook URL format` | Send a valid public webhook URL |
| `Transaction ID already used` | Generate a new unique transaction ID |
| `No enabled gateways found` | Retry later or contact support if it persists |

## Withdrawal validation errors

| Message | Resolution |
| --- | --- |
| `amount: Amount must be an integer (no decimals)` | Send a whole-number INR amount |
| `amount: Amount must be at least 100` | Increase the amount to at least INR 100 |
| `amount: Amount must not exceed 100000` | Reduce the amount to INR 100,000 or less |
| `transaction_id: Transaction ID must be at least 7 characters` | Use at least 7 characters |
| `transaction_id: Transaction ID must not exceed 32 characters` | Use no more than 32 characters |
| `Transaction ID already used` | Generate a new unique transaction ID |
| `No valid gateway strategy` | No payout gateway supports the request; contact support if it persists |

## Status and evidence errors

| Message | Resolution |
| --- | --- |
| `Deposit not found` | Use the same merchant key and transaction ID that created the deposit |
| `Withdrawal not found` | Use the same merchant key and transaction ID that created the withdrawal |
| `transaction_id: Transaction ID is required` | Include `transaction_id` in the request |
| `UTR already submitted` | Do not repeat the UTR or screenshot submission |
| `UPI ID does not belong to this deposit` | Omit `upi_id` or use the UPI ID for the deposit payment slot |
| `Deposit is already success/failed/rejected` | Stop submitting evidence and read the current status |
| `PDF file is required` | Attach a PDF in the `pdf` field |
| `Video file is required` | Attach a video in the `video` field |
| `Documents upload is not required for this deposit` | Upload documents only in the `need_pdf_video` state |

## Support escalation information

When contacting support, include:

- Merchant `transaction_id`.
- NiriPay `internal_transaction_id`, when available.
- UTC timestamp and endpoint path.
- HTTP status and complete response body.
- Sanitized request fields.

Never include the merchant API key, bank credentials, or unnecessary personal data.