Error Codes

This page documents all error codes returned by the TxnCheck API, along with their meanings and recommended solutions.

Error Response Format

All errors follow a consistent JSON format:

{
  "statusCode": 400,
  "message": "Human-readable error message",
  "error": "Error Type"
}

HTTP Status Codes

Status Code	Meaning
`200`	Success
`202`	Accepted - Request queued
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`402`	Payment Required - Insufficient balance
`403`	Forbidden - Access denied
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Authentication Errors

Missing API Key


HTTP Status	401
Message	Missing X-API-Key header
Cause	No `X-API-Key` header was provided
Solution	Include the `X-API-Key` header in your request

{
  "statusCode": 401,
  "message": "Missing X-API-Key header",
  "error": "Unauthorized"
}

Invalid API Key


HTTP Status	401
Message	Invalid API key
Cause	The provided API key is incorrect or doesn’t exist
Solution	Verify you’re using the correct API key from your dashboard

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

Merchant Deactivated


HTTP Status	403
Message	Merchant account is deactivated
Cause	Your merchant account has been deactivated
Solution	Contact support to reactivate your account

{
  "statusCode": 403,
  "message": "Merchant account is deactivated",
  "error": "Forbidden"
}

Invalid Signature


HTTP Status	401
Message	Invalid request signature
Cause	The HMAC signature doesn’t match the expected value
Solution	Verify your signature calculation (see Authentication docs)

{
  "statusCode": 401,
  "message": "Invalid request signature",
  "error": "Unauthorized"
}

Expired Timestamp


HTTP Status	401
Message	Request timestamp expired (signature older than 5 minutes)
Cause	The `X-Timestamp` header is more than 5 minutes old
Solution	Use the current timestamp when signing requests

{
  "statusCode": 401,
  "message": "Request timestamp expired (signature older than 5 minutes)",
  "error": "Unauthorized"
}

Authorization Errors

Method Not Allowed


HTTP Status	403
Message	Access to method '' is not allowed
Cause	Your merchant account doesn’t have access to this verification method
Solution	Contact your account manager to enable the method

{
  "statusCode": 403,
  "message": "Access to method 'full-check' is not allowed",
  "error": "Forbidden"
}

IP Not Whitelisted


HTTP Status	403
Message	Request from non-whitelisted IP
Cause	Your request came from an IP not in your whitelist
Solution	Add the IP to your whitelist in the dashboard

{
  "statusCode": 403,
  "message": "Request from non-whitelisted IP",
  "error": "Forbidden"
}

Payment Errors

Insufficient Balance


HTTP Status	402
Message	Insufficient wallet balance
Cause	Your merchant account doesn’t have enough balance for this request
Solution	Top up your account balance in the dashboard

{
  "statusCode": 402,
  "message": "Insufficient wallet balance",
  "error": "Payment Required"
}

Validation Errors

Invalid Mobile Number


HTTP Status	400
Message	Mobile must be in format +91XXXXXXXXXX (Indian number)
Cause	The mobile number doesn’t match the required format
Solution	Use Indian mobile format: `+91` followed by 10 digits

{
  "statusCode": 400,
  "message": ["Mobile must be in format +91XXXXXXXXXX (Indian number)"],
  "error": "Bad Request"
}

Invalid VPA Format


HTTP Status	400
Message	Each VPA must be in format username@bank
Cause	One or more VPAs don’t match the required format
Solution	Use format `username@bank` (e.g., `user@upi`)

{
  "statusCode": 400,
  "message": ["Each VPA must be in format username@bank (e.g., user@upi)"],
  "error": "Bad Request"
}

VPA Array Size


HTTP Status	400
Message	At least one VPA is required / Maximum 100 VPAs allowed per request
Cause	The VPA array is empty or exceeds the maximum size
Solution	Provide between 1 and 100 VPAs per request

{
  "statusCode": 400,
  "message": ["Maximum 100 VPAs allowed per request"],
  "error": "Bad Request"
}

Resource Errors

Request Not Found


HTTP Status	404
Message	Request not found
Cause	The request ID doesn’t exist or doesn’t belong to your merchant
Solution	Verify the request ID is correct

{
  "statusCode": 404,
  "message": "Request not found",
  "error": "Not Found"
}

Rate Limit Errors

Rate Limit Exceeded


HTTP Status	429
Message	Too Many Requests
Cause	You’ve exceeded the rate limit for this endpoint
Solution	Implement exponential backoff and retry

{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "Too Many Requests"
}

Rate Limits:

Endpoint Type	Limit
Verification endpoints	100 requests/minute
Status endpoints	300 requests/minute
Bulk endpoints	10 requests/minute

Request Status Error Classes

When a verification request fails, the error field contains details:

Error Class	Description	Recoverable
`VALIDATION_ERROR`	Input validation failed	Fix input data
`AUTH_ERROR`	Authentication/authorization issue	Check credentials
`PROVIDER_TEMPORARY`	Temporary provider issue	Retry later
`PROVIDER_BUSINESS_ERROR`	Provider rejected the request	Check input data

Example Failed Request

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "FAILED",
  "error": {
    "class": "PROVIDER_BUSINESS_ERROR",
    "message": "Mobile number not found in UPI system"
  },
  "webhookStatus": "SENT",
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:05.000Z"
}

Server Errors

Internal Server Error


HTTP Status	500
Message	Internal server error
Cause	An unexpected error occurred on our servers
Solution	Retry the request. If the issue persists, contact support.

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

Error Handling Best Practices

Log All Errors

Log error responses with request IDs for debugging

Retry with Backoff

Implement exponential backoff for 429 and 5xx errors

Validate Before Sending

Validate inputs client-side before API calls

Handle Gracefully

Show user-friendly messages, not raw API errors

Example Error Handler

async function makeApiRequest(endpoint, options) {
  try {
    const response = await fetch(endpoint, options);
    
    if (!response.ok) {
      const error = await response.json();
      
      switch (response.status) {
        case 401:
          // Re-authenticate or check API key
          throw new AuthenticationError(error.message);
        case 402:
          // Insufficient balance - alert admin
          throw new PaymentError(error.message);
        case 403:
          // Method not allowed - check permissions
          throw new AuthorizationError(error.message);
        case 429:
          // Rate limited - wait and retry
          const retryAfter = response.headers.get('Retry-After') || 60;
          await sleep(retryAfter * 1000);
          return makeApiRequest(endpoint, options);
        case 400:
          // Validation error - show to user
          throw new ValidationError(error.message);
        default:
          throw new ApiError(error.message, response.status);
      }
    }
    
    return response.json();
  } catch (error) {
    if (error.name === 'NetworkError') {
      // Network error - retry with backoff
      await sleep(1000);
      return makeApiRequest(endpoint, options);
    }
    throw error;
  }
}

Getting Started

Guides

SDKs

Use Cases

Security

API Reference

Reference

Error Codes

Error Codes

Error Response Format

HTTP Status Codes

Authentication Errors

Missing API Key

Invalid API Key

Merchant Deactivated

Invalid Signature

Expired Timestamp

Authorization Errors

Method Not Allowed

IP Not Whitelisted

Payment Errors

Insufficient Balance

Validation Errors

Invalid Mobile Number

Invalid VPA Format

VPA Array Size

Resource Errors

Request Not Found

Rate Limit Errors

Rate Limit Exceeded

Request Status Error Classes

Example Failed Request

Server Errors

Internal Server Error

Error Handling Best Practices

Log All Errors

Retry with Backoff

Validate Before Sending

Handle Gracefully

Example Error Handler

​Error Codes

​Error Response Format

​HTTP Status Codes

​Authentication Errors

​Missing API Key

​Invalid API Key

​Merchant Deactivated

​Invalid Signature

​Expired Timestamp

​Authorization Errors

​Method Not Allowed

​IP Not Whitelisted

​Payment Errors

​Insufficient Balance

​Validation Errors

​Invalid Mobile Number

​Invalid VPA Format

​VPA Array Size

​Resource Errors

​Request Not Found

​Rate Limit Errors

​Rate Limit Exceeded

​Request Status Error Classes

​Example Failed Request

​Server Errors

​Internal Server Error

​Error Handling Best Practices

Log All Errors

Retry with Backoff

Validate Before Sending

Handle Gracefully

​Example Error Handler

Error Codes

Error Response Format

HTTP Status Codes

Authentication Errors

Missing API Key

Invalid API Key

Merchant Deactivated

Invalid Signature

Expired Timestamp

Authorization Errors

Method Not Allowed

IP Not Whitelisted

Payment Errors

Insufficient Balance

Validation Errors

Invalid Mobile Number

Invalid VPA Format

VPA Array Size

Resource Errors

Request Not Found

Rate Limit Errors

Rate Limit Exceeded

Request Status Error Classes

Example Failed Request

Server Errors

Internal Server Error

Error Handling Best Practices

Example Error Handler