Error Codes

When the API encounters an error, it returns a structured error response with a machine-readable error_code that you can use for programmatic error handling.

Error Response Format

Every error response follows this consistent structure:

{
  "status": false,
  "error": {
    "code": 400,
    "error_code": "VALIDATION_INVALID_CURRENCY",
    "message": "Only INR currency is supported",
    "metadata": {
      "supported_currencies": ["INR"],
      "request_id": "abc123"
    }
  }
}

statusbooleanrequired

Always false for error responses.

error.codeintegerrequired

The HTTP status code of the error response.

error.error_codestringrequired

A machine-readable identifier for the specific error type. Use this for programmatic error handling.

error.messagestringrequired

A human-readable description of the error suitable for displaying to end users.

error.metadataobject

Additional context about the error, including the request_id for support inquiries.

Finding the Request ID

Every API request is assigned a unique request_id that helps our support team quickly identify and resolve issues.

You can find the request_id in two places:

Response Headers

The x-request-id header is included in all responses (both successful and failed):

x-request-id: req_abc123xyz

Response Body

For failed requests, the request_id is also included in the JSON response body under metadata:

{
  "status": false,
  "error": {
    "code": 400,
    "error_code": "VALIDATION_INVALID_CURRENCY",
    "message": "Only INR currency is supported",
    "metadata": {
      "supported_currencies": ["INR"],
      "request_id": "req_abc123xyz"
    }
  }
}

When contacting support, always provide the request_id to help us quickly investigate your issue.

Error Code Reference

Validation Errors

Validation errors occur when request data doesn't meet the required format or constraints. All validation error codes are prefixed with VALIDATION_.

VALIDATION_INVALID_CURRENCY

Property	Value
HTTP Status	`400`
Description	The specified currency is not supported. Currently only INR is accepted.

{
  "error_code": "VALIDATION_INVALID_CURRENCY",
  "message": "Only INR currency is supported",
  "metadata": {
    "supported_currencies": ["INR"]
  }
}

VALIDATION_AMOUNT_TOO_LOW

Property	Value
HTTP Status	`400` or `422`
Description	The transaction amount is below the minimum allowed threshold.

{
  "error_code": "VALIDATION_AMOUNT_TOO_LOW",
  "message": "Amount is below minimum threshold"
}

VALIDATION_PHONE_REQUIRED

Property	Value
HTTP Status	`400`
Description	Phone number is required but was not provided in the request.

{
  "error_code": "VALIDATION_PHONE_REQUIRED",
  "message": "Phone number is required"
}

VALIDATION_EMAIL_REQUIRED

Property	Value
HTTP Status	`400`
Description	Email address is required but was not provided in the request.

{
  "error_code": "VALIDATION_EMAIL_REQUIRED",
  "message": "Email address is required"
}

VALIDATION_NAME_REQUIRED

Property	Value
HTTP Status	`400`
Description	Name field is required but was not provided.

{
  "error_code": "VALIDATION_NAME_REQUIRED",
  "message": "Name is required"
}

VALIDATION_NAME_INVALID_FORMAT

Property	Value
HTTP Status	`400`
Description	Name must be in "FirstName LastName" format.

{
  "error_code": "VALIDATION_NAME_INVALID_FORMAT",
  "message": "Name must be in 'FirstName LastName' format"
}

VALIDATION_REDIRECT_URL_REQUIRED

Property	Value
HTTP Status	`400`
Description	Redirect URL is required for this payment flow.

{
  "error_code": "VALIDATION_REDIRECT_URL_REQUIRED",
  "message": "Redirect URL is required"
}

VALIDATION_USER_DETAILS_REQUIRED

Property	Value
HTTP Status	`400`
Description	User details object is required but was not provided.

{
  "error_code": "VALIDATION_USER_DETAILS_REQUIRED",
  "message": "User details are required"
}

VALIDATION_FAILED

Property	Value
HTTP Status	`400`
Description	Generic validation failure. Check metadata for specific field errors.

{
  "error_code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "metadata": {
    "fields": {
      "email": "Invalid email format",
      "amount": "Must be a positive number"
    }
  }
}

Authentication & Authorization Errors

Errors related to API authentication and access permissions. All authentication error codes are prefixed with AUTH_.

AUTH_UNAUTHORIZED

Property	Value
HTTP Status	`401`
Description	Authentication failed. Invalid credentials or missing/expired token.

{
  "error_code": "AUTH_UNAUTHORIZED",
  "message": "Authentication required"
}

AUTH_FORBIDDEN

Property	Value
HTTP Status	`403`
Description	Access denied. You don't have permission to perform this action.

{
  "error_code": "AUTH_FORBIDDEN",
  "message": "You do not have permission to perform this action"
}

AUTH_INVALID_API_KEY

Property	Value
HTTP Status	`401`
Description	The provided API key is invalid, malformed, or has been revoked.

{
  "error_code": "AUTH_INVALID_API_KEY",
  "message": "Invalid API key"
}

Payin Errors

Errors specific to payin (collection) transactions. All payin error codes are prefixed with PAYIN_.

PAYIN_DISABLED

Property	Value
HTTP Status	`500`
Description	Payin functionality is disabled for your account. Contact support.

{
  "error_code": "PAYIN_DISABLED",
  "message": "Payin functionality is disabled for this account"
}

PAYIN_DUPLICATE

Property	Value
HTTP Status	`400`
Description	A payin with this `merchant_order_no` already exists.

{
  "error_code": "PAYIN_DUPLICATE",
  "message": "A payment with this order number already exists",
  "metadata": {
    "existing_payment_id": "pay_abc123"
  }
}

Use idempotency keys or check for existing orders before creating new payments to avoid this error.

PAYIN_PROCESSING_FAILED

Property	Value
HTTP Status	`500`
Description	Failed to process the payment. Please try again later.

{
  "error_code": "PAYIN_PROCESSING_FAILED",
  "message": "Payment processing failed"
}

PAYIN_STATUS_FETCH_FAILED

Property	Value
HTTP Status	`500`
Description	Unable to retrieve the payment status at this time.

{
  "error_code": "PAYIN_STATUS_FETCH_FAILED",
  "message": "Unable to fetch payment status"
}

Payout Errors

Errors specific to payout (disbursement) transactions. All payout error codes are prefixed with PAYOUT_.

PAYOUT_DISABLED

Property	Value
HTTP Status	`500`
Description	Payout functionality is disabled for your account. Contact support.

{
  "error_code": "PAYOUT_DISABLED",
  "message": "Payout functionality is disabled for this account"
}

PAYOUT_DUPLICATE

Property	Value
HTTP Status	`400`
Description	A payout with this `merchant_order_no` already exists.

{
  "error_code": "PAYOUT_DUPLICATE",
  "message": "A payout with this order number already exists",
  "metadata": {
    "existing_payout_id": "pout_xyz789"
  }
}

PAYOUT_PROCESSING_FAILED

Property	Value
HTTP Status	`500`
Description	Failed to process the payout. Please try again later.

{
  "error_code": "PAYOUT_PROCESSING_FAILED",
  "message": "Payout processing failed"
}

PAYOUT_STATUS_FETCH_FAILED

Property	Value
HTTP Status	`500`
Description	Unable to retrieve the payout status at this time.

{
  "error_code": "PAYOUT_STATUS_FETCH_FAILED",
  "message": "Unable to fetch payout status"
}

PAYOUT_INSUFFICIENT_BALANCE

Property	Value
HTTP Status	`400`
Description	Insufficient available balance to complete this payout.

{
  "error_code": "PAYOUT_INSUFFICIENT_BALANCE",
  "message": "Insufficient balance",
  "metadata": {
    "available_balance": "1000.00",
    "requested_amount": "1500.00"
  }
}

Check your wallet balance using the Get Balance endpoint before initiating payouts to avoid this error.

Transaction Errors

General transaction-related errors applicable to both payins and payouts. All transaction error codes are prefixed with TRANSACTION_.

TRANSACTION_NOT_FOUND

Property	Value
HTTP Status	`404`
Description	The specified transaction does not exist.

{
  "error_code": "TRANSACTION_NOT_FOUND",
  "message": "Transaction not found"
}

TRANSACTION_ACCESS_DENIED

Property	Value
HTTP Status	`403`
Description	You are not authorized to view or modify this transaction.

{
  "error_code": "TRANSACTION_ACCESS_DENIED",
  "message": "You do not have access to this transaction"
}

Wallet Errors

Errors related to merchant wallet and balance operations. All wallet error codes are prefixed with WALLET_.

WALLET_BALANCE_UPDATE_FAILED

Property	Value
HTTP Status	`400`
Description	Failed to update wallet balance. This may occur due to concurrent operations or insufficient funds.

{
  "error_code": "WALLET_BALANCE_UPDATE_FAILED",
  "message": "Failed to update wallet balance"
}

WALLET_BALANCE_FETCH_FAILED

Property	Value
HTTP Status	`500`
Description	Unable to retrieve wallet balance at this time.

{
  "error_code": "WALLET_BALANCE_FETCH_FAILED",
  "message": "Unable to fetch wallet balance"
}

Internal Errors

Server-side errors that are not caused by client input. All internal error codes are prefixed with INTERNAL_.

INTERNAL_ERROR

Property	Value
HTTP Status	`500`
Description	An unexpected internal error occurred. Please contact support if the issue persists.

{
  "error_code": "INTERNAL_ERROR",
  "message": "An internal error occurred",
  "metadata": {
    "request_id": "req_abc123xyz"
  }
}

When reporting internal errors to support, always include the request_id from the metadata to help with troubleshooting.

Error Code Quick Reference

Error Code	HTTP Status	Category
`VALIDATION_INVALID_CURRENCY`	400	Validation
`VALIDATION_AMOUNT_TOO_LOW`	400/422	Validation
`VALIDATION_PHONE_REQUIRED`	400	Validation
`VALIDATION_EMAIL_REQUIRED`	400	Validation
`VALIDATION_NAME_REQUIRED`	400	Validation
`VALIDATION_NAME_INVALID_FORMAT`	400	Validation
`VALIDATION_REDIRECT_URL_REQUIRED`	400	Validation
`VALIDATION_USER_DETAILS_REQUIRED`	400	Validation
`VALIDATION_FAILED`	400	Validation
`AUTH_UNAUTHORIZED`	401	Authentication
`AUTH_FORBIDDEN`	403	Authentication
`AUTH_INVALID_API_KEY`	401	Authentication
`PAYIN_DISABLED`	500	Payin
`PAYIN_DUPLICATE`	400	Payin
`PAYIN_PROCESSING_FAILED`	500	Payin
`PAYIN_STATUS_FETCH_FAILED`	500	Payin
`PAYOUT_DISABLED`	500	Payout
`PAYOUT_DUPLICATE`	400	Payout
`PAYOUT_PROCESSING_FAILED`	500	Payout
`PAYOUT_STATUS_FETCH_FAILED`	500	Payout
`PAYOUT_INSUFFICIENT_BALANCE`	400	Payout
`TRANSACTION_NOT_FOUND`	404	Transaction
`TRANSACTION_ACCESS_DENIED`	403	Transaction
`WALLET_BALANCE_UPDATE_FAILED`	400	Wallet
`WALLET_BALANCE_FETCH_FAILED`	500	Wallet
`INTERNAL_ERROR`	500	Internal

Handling Errors

Best Practices

Use error_code for programmatic handling
Always use the error_code field for programmatic error handling rather than parsing the message string, which may change over time.
Display user-friendly messages
The message field contains human-readable text suitable for displaying to end users. You can also map error codes to your own localized messages.
Log the request_id
Always log the metadata.request_id value. This helps support teams trace and resolve issues quickly when you contact them.
Handle error categories
You can handle error categories by checking the prefix. For example, all VALIDATION_* errors can trigger form validation feedback in your UI.

Changelog

Version	Date	Changes
1.0.0	2026-01-20	Initial error code documentation

Error Codes

On this page