---
title: "Status & Error Codes"
description: "HTTP status codes, transaction status ids, and the response envelope."
canonical: "https://eps.eko.in/docs/error-codes"
---


> **Canonical URL:** https://eps.eko.in/docs/error-codes
> This is a machine-readable Markdown version of the page for AI agents and LLMs. The primary (HTML) version lives at the canonical URL above.

# Status & Error Codes

Eko APIs report status at two levels: the transport-level **HTTP status code**
and the business-level **`response_status_id`** inside the response envelope. A
`200 OK` with a non-zero `response_status_id` is a successful call that returned
a business error — always check both.

## HTTP Status Codes

| Code  | Meaning                                                                                                                                                                                      |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | OK — response returned by our system.                                                                                                                                                        |
| `403` | Forbidden — incorrect `secret-key` or timestamp. See [how authentication works](/docs/how-auth-works) or [test your generated secret-key](/docs/how-auth-works#try-it-secret-key-playground) |
| `404` | Not Found — wrong request URL.                                                                                                                                                               |
| `415` | Unsupported Media Type — wrong `Content-Type` header.                                                                                                                                        |
| `500` | Internal Server Error — connectivity or URL misconfiguration.                                                                                                                                |

## The Response Structure

| Field                | Type   | Meaning                                                      |
| -------------------- | ------ | ------------------------------------------------------------ |
| `status`             | number | Primary success indicator (`0` = success).                   |
| `response_status_id` | number | Granular status id — the codes above.                        |
| `response_type_id`   | number | Response type id for non-financial requests.                 |
| `tx_status`          | number | Financial Transactions status code (`0` = success)           |
| `message`            | string | Human-readable result or error message.                      |
| `data`               | object | Rest of the response parameters specific to that transaction |

## Input Validation Errors

In case of input parameter validation errors, you will receive and error (non-zero) `status` code, `response_status_id = 1`, `response_type_id = -1`, and the response will contain `invalid_parameters` object with each invalid parameter name and its error message. This can be used to show proper error response in the user-input form itself.

For example:

```json
{
	"status": 461,
	"response_status_id": 1,
	"response_type_id": -1,
	"invalid_params": {
		"name": "Name too long",
		"dob": "Must be over 18 years",
	},
	...
}
```

## Financial Transaction Status Codes (`tx_status`)

Financial (money-debit) responses additionally carry `tx_status` and `txstatus_desc`. When `tx_status` is `2` (Awaited), poll the relevant status endpoint rather than retrying the debit.

| tx_status | Meaning                                         |
| --------- | ----------------------------------------------- |
| `0`       | Success                                         |
| `1`       | Failed                                          |
| `2`       | Initiated (In case of NEFT Money Transfer)      |
| `3`       | Refund Pending                                  |
| `4`       | Refunded                                        |
| `6`       | Response Awaited (Transaction Inquiry Required) |

## Common Transaction Status Codes (`status`)

For all financial transactions, **status = 0** should be treated as successful else failed. The current state of a financial transaction can be retrieved from **tx_status** and **txstatus_desc** parameters.

For all non-financial requests, you may need to consider both status and response_type_id parameters.

Here are some of the common `status` codes:

| status | Meaning                                                   |
| ------ | --------------------------------------------------------- |
| `0`    | Success                                                   |
| `17`   | User wallet already exists                                |
| `132`  | Sender name should only contain letters                   |
| `302`  | Wrong OTP                                                 |
| `303`  | OTP expired                                               |
| `319`  | Invalid `initiator_id`. User does not exist in our system |
| `327`  | Enrollment done; verification pending                     |
| `342`  | Recipient already registered                              |
| `346`  | User/agent not onboarded or wrong `user_code`             |
| `347`  | Insufficient balance                                      |
| `463`  | User not found                                            |
| `585`  | Customer already KYC approved                             |
| `945`  | Sender/beneficiary monthly limit exhausted                |
| `1297` | User/Agent not onboarded                                  |