> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Code Mapping

Error Code would match with the http status code in most cases.
4XX indicates a user error and 5XX indicates a server side error.

## By symptom

Start here when you know what you see but not which code it is. Each symptom lists the likely causes, what to check, the codes involved and the workflow step it belongs to.&#x20;

### OTP never arrives

Belongs to: the Generate OTP step of [Create an ABHA with Aadhaar OTP](https://developer.eka.care/docs/hie-cm/workflows/create-abha-aadhaar-otp.md), [Create an ABHA address with mobile OTP](https://developer.eka.care/docs/hie-cm/workflows/create-abha-mobile-otp.md) and [Log in to an existing ABHA](https://developer.eka.care/docs/hie-cm/workflows/login-abha.md).

| Likely cause | What to check | Codes |
| - | - | - |
| The patient is checking the wrong phone. The Aadhaar OTP goes to the mobile linked to the Aadhaar, not the `mobile` you send. | Show the patient the masked number in `hint` from the init response. | none |
| The OTP is delayed or lost. | Call the workflow's resend operation with the current `txn_id`, then use the `txn_id` it returns. | none |
| Too many OTP requests in this transaction. | Tell the patient to try again in 30 minutes, then start again from Generate OTP. | `ABDM-1100` |
| ABDM's SMS gateway is unavailable. | Retry later. | `ABDM-1004` |
| In [Answer discovery and link old records](https://developer.eka.care/docs/hie-cm/workflows/hip-discovery-and-link.md), your HIP sends this OTP itself. | Check your own SMS sending. | none |

### The patient is locked out after entering OTPs

Belongs to: the Verify OTP step of every ABHA creation, login and gateway session workflow.

| Likely cause | What to check | Codes |
| - | - | - |
| The OTP is wrong. | Ask the patient to re-enter it. | `MIS-1013`, `ABDM-1035` (OTP does not match, in [Discover and link records from a facility](https://developer.eka.care/docs/hie-cm/workflows/phr-discover-and-link.md)) |
| Too many wrong attempts or OTP requests. | Tell the patient to try again in 30 minutes. | `ABDM-1100` |
| The patient is blocked. | Tell the patient to try again after 24 hours. | `ABDM-1027` |
| The transaction expired. | Start again from Generate OTP. | `ABDM-1017`, `MIS-1026` |

### Every call returns 401

Belongs to: every call. See [Authorization](https://developer.eka.care/api-sdk/auth/getting-started.md).

| Likely cause | What to check | Codes |
| - | - | - |
| Your access token has expired. | Get a new token with [Refresh token](https://developer.eka.care/api-sdk/auth/refresh-token-v2.md) and retry. | HTTP `401` |
| The token is missing from the request. | Send it as a Bearer token on every call. | HTTP `401` |

### Patient calls return 491

Belongs to: [Hold the ABHA Gateway session](https://developer.eka.care/docs/hie-cm/workflows/hold-gateway-session.md), and every patient-scoped call in the PHR workflows, such as [Approve, deny or revoke a consent in a PHR app](https://developer.eka.care/docs/hie-cm/workflows/phr-act-on-consent.md) and [Manage the ABHA profile and KYC](https://developer.eka.care/docs/hie-cm/workflows/manage-profile-and-kyc.md).

| Likely cause | What to check | Codes |
| - | - | - |
| The patient's ABHA Gateway session has expired. | Run Session Init and Session Verify with a mobile OTP, then retry the call. See [User Session](https://developer.eka.care/docs/hie-cm/session/getting-started.md). | HTTP `491` |
| You called Session Status without the patient's id. | Send the patient's `oid` in `X-Pt-Id`. | not documented |

### A webhook never arrives

Belongs to: every workflow that waits on an event. See [Webhooks](https://developer.eka.care/docs/hie-cm/webhooks).

| Likely cause | What to check | Codes |
| - | - | - |
| Your endpoint is not registered with Eka, or is not reachable. | Check the registration with [Get webhooks](https://developer.eka.care/api-sdk/webhooks/get-webhooks.md). Check the URL is public, uses HTTPS, and allows Eka's IP addresses. | none |
| Your endpoint does not reply `200` within 5 seconds. | Reply first, then process. Eka retries on any other status. | none |
| Your signature check rejects the event. | Compare your check with [Webhook signature](https://developer.eka.care/docs/webhooks/webhook-signature.md). | none |
| The event is not sent in your setup. `abha.hip_data_fetch` is sent only if you keep the health data yourself. `abha.hiu_data_push` is sent only if you manage the data on your side; if Eka stores it, read the records instead. | Check whether Eka stores the data for you. | none |
| For `abha.hiu_data_push`: your public keyset is not registered. | Register it as in [Request a patient's consent as a HIU](https://developer.eka.care/docs/hie-cm/workflows/hiu-request-consent.md). | none |
| For UHI events: the result is late. | Read the result with the matching `GET`, as in [Book a physical consultation over UHI](https://developer.eka.care/docs/uhi/workflows/uhi-book-consultation.md). | none |

When `abha.created` does not arrive, use the Create response to proceed.&#x20;

### A consent request never moves on

Belongs to: the wait-for-status step of [Request a patient's consent as a HIU](https://developer.eka.care/docs/hie-cm/workflows/hiu-request-consent.md).

| Likely cause | What to check | Codes |
| - | - | - |
| The patient has not acted on the request yet. | The patient approves or denies it in their PHR app. | none |
| `abha.consent_update` is not reaching you. | Check your webhook registration and signature check, then read the status from [Consent List](https://developer.eka.care/api-sdk/hie-cm/consents/consent-list.md). | none |
| The request expired before the patient acted. | Raise a new consent request; do not retry the old one. | `ABDM-1061` |
| The patient denied the request. | Close the request on your side. | `ABDM-1062` |

### Records do not decrypt

Belongs to: the decrypt step of [Receive and decrypt records as a HIU](https://developer.eka.care/docs/hie-cm/workflows/hiu-receive-data.md), and the encrypt step of [Serve records on a fetch request](https://developer.eka.care/docs/hie-cm/workflows/serve-data-on-fetch.md).

| Likely cause | What to check | Codes |
| - | - | - |
| As a HIU: you used a different key pair from the one registered for this consent. | Use the `private_key` and `nonce` registered at the time of the consent. Report the entry with `success` `false`. | none |
| As a HIU: a field sent to Ecdh decrypt is not the Base64 value you received. | Send each field exactly as it came in the webhook or your store. | `ABDM-1006`, `ABDM-1010` |
| As a HIP: you encrypted with the wrong receiver key or nonce. | Take the receiver key and nonce from `key_information` in this `abha.hip_data_fetch` event. | not documented |

### A care context link reports ERRORED

Belongs to: the wait-for-status step of [Link a care context as a HIP](https://developer.eka.care/docs/hie-cm/workflows/link-care-context-hip.md).

| Likely cause | What to check | Codes |
| - | - | - |
| ABDM rejected the link. | Read `data.error` in `abha.link_care_context`. Correct the request and link again. | `data.status` `ERRORED` |
| The ABHA address or number is not recognised. | Check the `abha_address` saved on the patient record. | `ABDM-1051` |
| The HIP ID is wrong. | Check the `X-Hip-Id` header against your onboarded HIP ID. | `ABDM-1035` (Invalid HIP ID) |
| The gateway or a dependent service is down. | Retry later. | `ABDM-1019`, `ABDM-1024`, `ABDM-1048` |

## By code

Codes that start with `EKA-` come from Eka's own service and arrive in `source_error.code`. Codes that start with `ABDM-` or `MIS-` come from NHA.

| code | message | abdm-code | abdm-message |
| - | - | - | - |
| 500 | Something went wrong | ABDM-1000 | Unable to connect the database |
| 500 | No data found | ABDM-1001 | No data found |
| 500 | Something went wrong | ABDM-1002 | Integrity violation |
| 500 | Something went wrong | ABDM-1003 | Email Gateway is unavailable |
| 500 | Something went wrong | ABDM-1004 | SMS Gateway is unavailable |
| 500 | Something went wrong | ABDM-1005 | Invalid receiver |
| 400 | Bad Request, invalid request | ABDM-1006 | Bad Request, invalid request Body |
| 500 | Something went wrong | ABDM-1007 | Connection failed due to timeout |
| 500 | Something went wrong | ABDM-1008 | SMS service currently disabled |
| 500 | Something went wrong | ABDM-1009 | Email service currently disabled |
| 400 | Validation failed | ABDM-1010 | Validation failed |
| 500 | Something went wrong | ABDM-1011 | Gateway database unavailable |
| 400 | No records found against the ABHA Address | ABDM-1012 | No records found against the ABHA Address |
| 400 | Invalid ABHA Number | ABDM-1013 | Invalid ABHA Number |
| 400 | Invalid Mobile Email | ABDM-1014 | Invalid Mobile Email |
| 500 | Something went wrong | ABDM-1015 | Invalid Response |
| 500 | Something went wrong | ABDM-1016 | Invalid TimeStamp |
| 500 | Something went wrong | ABDM-1017 | Invalid TransactionId |
| 500 | Unable to share the details with Hospital | ABDM-1018 | Share Profile database unavailable |
| 500 | Something went wrong | ABDM-1019 | Dependent Service Unavailable |
| 500 | Something went wrong | ABDM-1020 | Unknown database |
| 500 | Something went wrong | ABDM-1021 | ABDM-1021 |
| 500 | Too many requests | ABDM-1022 | Too many requests |
| 500 | Something went wrong | ABDM-1023 | Invalid User |
| 500 | Something went wrong | ABDM-1024 | Dependent service unavailable |
| 500 | Something went wrong | ABDM-1025 | Invalid ServiceId |
| 500 | Something went wrong | ABDM-1026 | Invalid Link Token |
| 500 | You are blocked. Please try again after 24 hours. | ABDM-1027 | You are blocked. Please try again after 24 hours. |
| 500 | Something went wrong | ABDM-1028 | HIP is unavailable |
| 500 | Something went wrong | ABDM-1029 | Redis server is unavailable |
| 400 | Something went wrong | ABDM-1030 | Invalid request ID |
| 400 | Something went wrong | ABDM-1031 | Invalid request |
| 400 | Something went wrong | ABDM-1032 | Invalid header |
| 500 | Something went wrong | ABDM-1033 | HIU is unavailable |
| 500 | Something went wrong | ABDM-1034 | Notification service unavailable |
| 500 | Something went wrong | ABDM-1035 | Invalid HIP ID |
| 400 | OTP doesn't match | ABDM-1035 | OTP does not matched |
| 500 | Something went wrong | ABDM-1036 | Data does not matched |
| 500 | Something went wrong | ABDM-1037 | Counter and Care context count mismatch |
| 500 | Something went wrong | ABDM-1038 | ABHA address and Link token mismatch |
| 500 | Something went wrong | ABDM-1039 | Invalid Consent request id |
| 500 | Something went wrong | ABDM-1040 | Invalid HIU ID |
| 500 | Something went wrong | ABDM-1041 | Invalid Acknowledgement |
| 400 | Invalid request | ABDM-1042 | Provider Mandatory |
| 500 | Something went wrong | ABDM-1043 | ABHA Address does not match with KYC details. |
| 500 | Something went wrong | ABDM-1044 | Broadcast Failed |
| 500 | Something went wrong | ABDM-1045 | Database Access is restricted |
| 500 | Something went wrong | ABDM-1046 | Invalid Purpose |
| 500 | Something went wrong | ABDM-1047 | Purpose does not exist |
| 500 | Something went wrong | ABDM-1048 | Timeout |
| 500 | Something went wrong | ABDM-1049 | Invalid Profile Share Intent Keys |
| 500 | Something went wrong | ABDM-1050 | Invalid Profile Share Metadata Keys |
| 500 | Something went wrong | ABDM-1051 | Invalid ABHA Number or ABHA Address |
| 500 | Something went wrong | ABDM-1052 | Invalid TransactionId or response's requestId |
| 500 | Something went wrong | ABDM-1053 | Data already exists |
| 500 | Something went wrong | ABDM-1054 | Invalid Subscription Request Id |
| 500 | Something went wrong | ABDM-1401 | HIP is not available |
| 500 | Something went wrong | ABDM-1402 | Acknowledgement is not received from HIP |
| 500 | Something went wrong | ABDM-9999 | Unknown exception |
| 400 | Consent artefact expired | ABDM-1061 | Consent artefact expired |
| 400 | Consent Not granted | ABDM-1062 | Consent Not granted |
| 400 | Date Range given is invalid | ABDM-1063 | Date Range given is invalid |
| 400 | Something went wrong | ABDM-1064 | request with this request id already exists |
| 500 | Something went wrong | ABDM-1109 | ABHA DB service unavailable |
| 500 | Something went wrong | ABDM-1108 | Notification DB service unavailable |
| 500 | Something went wrong | ABDM-1205 | Document DB Gateway is unavailable |
| 500 | Something went wrong | ABDM-1202 | Document Gateway is unavailable |
| 500 | Something went wrong | ABDM-1200 | LGD Gateway is unavailable |
| 500 | Something went wrong | ABDM-1201 | IDP Gateway is unavailable |
| 500 | Something went wrong | ABDM-1101 | This ABHA Address already exists. Please create with unique ABHA Address |
| 500 | Something went wrong | ABDM-1006 | Invalid combinations of scopes |
| 500 | Something went wrong | ABDM-1100 | You have requested multiple OTPs Or Exceeded maximum number of attempts for OTP match in this transaction. Please try again in 30 minutes. |
| 500 | ABHA User not found. | ABDM-1110 | ABHA User not found. |
| 400 | Mobile number not found. | ABDM-1111 | Mobile number not found. |
| 400 | Aadhaar details not found. | ABDM-1112 | Aadhaar details not found. |
| 400 | Login via Password is not allowed | ABDM-1113 | Login via Password is not allowed |
| 400 | Login via ABHA Number OTP is not allowed | ABDM-1114 | Login via ABHA Number OTP is not allowed |
| 400 | Login via Aadhaar OTP is not allowed | ABDM-1115 | Login via Aadhaar OTP is not allowed |
| 400 | Mobile number verification is pending. | ABDM-1102 | Mobile number verification is pending. |
| 400 | The OTP that you have entered is incorrect. Please try again. | MIS-1013 | OTP(One Time Password) is invalid, Please enter the correct OTP. |
| 500 | Transaction not found for UUID. | MIS-1026 | Transaction is not found for UUID. |
| 400 | This account has already been claimed by the mobile number: `mobile_number` | EKA-1001 | This account has already been claimed by the mobile number: `mobile_number` |
| 400 | This account has already been claimed by another mobile number: `mobile_number` | EKA-1002 | This ABHA belongs to a different mobile number, shown in the message (last 10 digits). Use that mobile number. |
| 400 | Session expired. Please try again. | EKA-1003 | The transaction was not found or has expired. Start the flow again with a new OTP or a new session. |
| 400 | Some details are missing or not valid. Please check and try again. | EKA-1004 | A field in the request is missing, malformed or not accepted. Check the request body. |
| 400 | Please enter at least 3 letters to search. | EKA-1004 | The search name is too short. Send at least 3 letters. |
| 404 | We could not find this ABHA. Please check the details and try again. | EKA-1005 | Check the ABHA number or address sent. If it is correct, the ABHA does not exist. If the user has no ABHA linked, see EKA-1015. |
| 500 | Something went wrong. Please try again. | EKA-1006 | A problem on Eka's side, such as a store or search failure. Retry later. If it continues, contact support. |
| 400 | Invalid aadhaar number | EKA-1007 | The Aadhaar number failed validation before ABDM was called. Ask the user to re-enter it. Do not retry the same value. |
| 400 | Invalid mobile number | EKA-1008 | Ask the user to re-enter a valid 10-digit mobile number. |
| 400 | An ABHA `health_id` already exists for your profile | EKA-1009 | This profile already has an ABHA, shown in the message. Use it. Do not create another. |
| 400 | You have reached the maximum number of ABHA that can be created for this mobile | EKA-1010 | Do not retry. This mobile has reached its limit for creating ABHA. Contact support. |
| 400 | Please enter a valid date of birth. | EKA-1011 | Ask the user to enter a real date of birth. |
| 400 | Invalid ABHA number | EKA-1012 | Ask the user to re-enter the 14-digit ABHA number. |
| 403 | ABHA search is turned off for your workspace. | EKA-1013 | Do not retry. ABHA search is off for this workspace. Contact support to turn it on. |
| 429 | Too many requests. Please try again later. | EKA-1014 | Wait, then retry. Slow down the request rate. |
| 400 | No ABHA is linked to your profile. Please link one and try again. | EKA-1015 | Ask the user to create or link an ABHA first. |
| 400 | We could not find your workspace. Please sign in again, or contact support if this continues. | EKA-1016 | Ask the user to sign in again. If it continues, contact support. |
| 404 | We could not find this consent request. Please check the request ID and try again. | EKA-1017 | Check the consent request ID and health ID sent. If they are correct, the consent request does not exist. |
| 403 | Not authorised to access this profile | EKA-1018 | Do not retry. This profile is not linked to the caller's clinics. Contact support. |
| 400 | Your healthcare facility is not onboarded on HMIS yet. Please reach out to our support team. | EKA-1019 | Do not retry. The clinic is not onboarded on HMIS. Contact support. |
| 400 | This HIP ID is not linked to your workspace. Check the ID, or link it in Eka Console. | EKA-1020 | Check the HIP ID sent. If it is correct, link the facility to the workspace in Eka Console (ABDM Connect). If it is already linked, contact support. |
| 404 | We could not find this facility. Please check the facility ID and try again. | EKA-1021 | Check the facility ID sent. If it is correct, the facility does not exist in the HFR. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.