Success & Error Codes

Understanding HTTP status codes and error responses to build robust integrations.

---

Understanding Response Codes

We use standard HTTP status codes to communicate the outcome of API requests. Use the status code to drive your business logic and remedial actions.

Range	Meaning
2XX	Request processed successfully — response body contains the expected data.
4XX	Client error — inspect and correct the request before retrying.
5XX	Server error — treat as transient; consider retrying after a delay.

---

Common Error Status Codes

When a request fails, our APIs return an error payload describing the issue.

HTTP Status	Error Code	Description / Cause	Recommended Action
400	BAD_REQUEST	Request has malformed or missing data.	Validate request data against API schema. Fix missing/incorrect fields.
401	UNAUTHORISED_ACCESS	Authentication failed — missing or invalid credentials.	Ensure Authorization header is correct and key is valid.
402	No active subscription	Account subscription is inactive or expired.	Contact support to activate or renew subscription.
403	MERCHANT_CREDITS_EXPIRED	Account has exhausted credits required for API calls.	Acquire more credits — contact support to top up.
422	NO_RECORD_FOUND	API could not find any matching record based on input.	Verify input data is correct and refers to existing records.
443	MAX_RETRIES_EXCEEDED	Rate-limit exceeded (too many requests).	Wait for cooldown period and retry. Implement rate-limiting logic.
500	INTERNAL_SERVER_ERROR	Unexpected error occurred on server side.	Retry after some time. If persistent, contact support with requestId.
503	INTERNAL_SERVICE_UNAVAILABLE	Service temporarily unable to handle request.	Retry after some time with backoff. Contact support if persistent.
504	Endpoint request timed out	Request took too long to process.	Retry after delay. Consider adding timeout and retry logic.

note

The list above covers common cases. Additional or custom error codes may appear depending on the endpoint, account configuration, or business logic. Always inspect the full error payload for details.

---

Error Response Format

When the API returns an error, the response body follows this JSON schema:

{
  "error": {
    "code": <integer>,         // HTTP status code or custom error code
    "description": "string",   // Brief description of the error
    "message": "string",       // Human-readable error message
    "metadata": { } | null,    // Optional additional info
    "referenceId": "string",   // Unique ID for the error/request
    "type": "string"           // Error type (e.g. BAD_REQUEST)
  },
  "merchantId": "string",      // Your account / merchant identifier
  "requestId": "string",       // Unique request identifier
  "statusCode": <integer>,     // HTTP status code
  "timestamp": <integer>       // Unix timestamp in milliseconds
}

---

Sample 400 Error Response

{
  "error": {
    "code": 400,
    "description": "Request does not contain ifsc param in request body",
    "message": "IFSC is missing",
    "metadata": null,
    "referenceId": "",
    "type": "BAD_REQUEST"
  },
  "merchantId": "org_qMOPL369km74RKOz",
  "requestId": "RNlVKFM0BcwEDGA=",
  "statusCode": 400,
  "timestamp": 1725268007691
}