Error Codes

The API uses conventional HTTP status codes and returns a JSON body with a human-readable message.

Error shape

Most errors return one of these shapes. Branch on the HTTP status, then read the message:

Service error

400 Bad Request

{
    "success": false,
    "message": "Refund is allowed only for successful transactions.",
    "data": null
}

Auth error

401 Unauthorized

{
    "detail": "Invalid authentication hash."
}

Reference

Search this page (press /) to jump to a specific message.

Status	Message	Reason	Resolution
400	`transaction_id and transaction_amount is required.`	A required field is missing from the request body.	Include all required parameters before signing.
400	`Invalid amount or less than 1 rupee`	`transaction_amount` is below the ₹1.00 minimum.	Send an amount ≥ 1.00 with two decimals.
400	`Already exists`	The `merchant_transaction_id` was already used.	Generate a unique reference per order.
400	`No Routing Rule found for this amount.`	No active routing rule covers the amount.	Configure a routing rule, or contact support.
400	`Transaction cannot be cancelled as it is already processed`	The transaction is no longer in `INITIATED` state.	Only cancel transactions that are still initiated.
400	`Refund is allowed only for successful transactions.`	The original payment is not `SUCCESS`.	Refund only successful payments.
400	`Refund amount exceeds refundable balance…`	Refund + prior refunds exceed the original amount.	Refund at most the remaining refundable balance.
401	`Unauthorized.`	Missing or unknown API key.	Send a valid `X-API-Key` for an active account.
401	`Invalid authentication hash.`	The computed `Hash` does not match.	Recompute the hash with the correct fields, values and salt.
404	`Transaction not found`	No transaction matches the reference.	Verify the `merchant_transaction_id` / `transaction_id`.
404	`Refund not found.`	No refund matches the `refund_id`, or it is not yours.	Use a `refund_id` returned by Refund Initiate.
429	`Too Many Requests`	You exceeded your rate limit.	Back off and retry with jitter; request a higher quota if needed.
500	`Internal server error`	An unexpected error occurred server-side.	Retry with backoff; contact support if it persists.

HTTP status summary

Status	Meaning
200 OK	Success (may return a resource or an array).
201 Created	Resource created (payment or refund).
400 Bad Request	Invalid request — missing/invalid parameters or a business-rule violation.
401 Unauthorized	Authentication failed — bad key or hash.
404 Not Found	The referenced resource was not found.
429 Too Many Requests	Rate limited — slow down and retry.
500 Internal Server Error	Unexpected server error — safe to retry with backoff.

Idempotency & retries

On 5xx or network errors it is safe to retry. Reuse the same merchant_transaction_id so a retried Initiate Payment cannot create a duplicate order.