M1 ABHA identity errors

Seeing a symptom rather than a code? Start at Troubleshooting.

Six error shapes, not one​

Do not write a parser that expects a single shape. Four come from the ABHA service and its gateway. The fifth is an empty body. The sixth comes from the registries and hides its real code one level down.

Shape 1: the wrapped ABDM error​

{
    "error": {
        "code": "ABDM-1204",
        "message": "UIDAI Error code : 300 : Biometric data did not match."
    }
}

The code lives at error.code. This comes from the ABHA service's own business logic.

Do not compare that code with string equality. It is not always a clean token: a failed session call returned {"error":{"code":"ABDM-9999: ", "message":"Invalid user credentials"}}, with a trailing colon and space inside the code. Trim it and match on the ABDM-nnnn prefix, or the branch you wrote for that code never runs.

Shape 2: the flat ABDM error​

{
    "code": "ABDM-1094",
    "message": "Access to this feature is restricted. Please contact NHA to enable it.",
    "timestamp": "2024-10-25 15:02:34"
}

Same family of codes, no error wrapper, plus a timestamp. The collection shows ABDM-1094 in both shapes on different calls, so the wrapper is not tied to the code. Read error.code first and fall back to a top level code.

Shape 3: field validation​

{
    "txnId": "Invalid Transaction Id",
    "timestamp": "2025-01-15 13:21:16"
}

No code at all. The key names the field you got wrong. Several bad fields produce several keys:

{
    "scope": "Invalid Scope",
    "authData": "Invalid Auth Data",
    "timestamp": "2025-01-15 13:39:03"
}

Treat every key except timestamp as a field name. These always arrive as HTTP 400.

Two of these read almost the same. Only one of them tells you anything.

The first is the one that costs an afternoon, because the value really was encrypted and really was the right number. An ABHA number keeps its dashes, NN-NNNN-NNNN-NNNN.

The second carries no diagnostic value on /v3/enrollment/request/otp. That endpoint returns it for plaintext, for an empty string, for base64 that is not ciphertext, and for a correctly encrypted value alike. A padding matrix run against it returns the same refusal for every row, the correct row included, which is how a wrong padding survives a test that looks thorough.

Test encryption against POST /v3/profile/login/request/otp with loginHint: "mobile" instead, and with a number that is registered against an ABHA account. The 200 is the signal: a right padding returns it with a txnId, a wrong one returns Invalid Mobile Number.

The number has to be a real one. A correctly encrypted 9999999999 returns that same Invalid Mobile Number, because the value decrypted fine and named nobody. With an unregistered number this endpoint is as uninformative as the enrolment one.

The algorithm is published: read encryptionAlgorithm from the certificate response. The plaintext shape for every encrypted field is in encryption.

Shape 4: the API gateway error​

{
    "code": "900901",
    "message": "Invalid Credentials",
    "description": "Invalid JWT token. Make sure you have provided the correct security credentials"
}

A numeric code, not an ABDM- code, plus a description field the other shapes lack. This comes from the API gateway in front of the ABHA service, before your request reaches the business logic. It almost always means the Authorization header is wrong or expired.

900901 is a bad token. 900902 is no token at all, observed on the NHPR host. Match the family, not the single code.

Shape 5: the empty body​

An HTTP 401 with a zero length body and no JSON at all, observed on /v3/phr/web/login/profile/abha-profile when no user token was sent. There is nothing to parse and nothing to match. Code that assumes every failure carries a body throws here, on a response that means something simple.

Shape 6: the registry error, with the real code nested​

{
    "code": "HIS-422",
    "message": "Unable to process the current request due to some wrong data entered.",
    "details": [
        {"message": "You are not allowed to access this API", "code": "HIS-403", "attribute": null}
    ]
}

The registries return a HIS- family rather than ABDM-, and the top level code is not the cause. HIS-422 and its message say the data was wrong. The real reason is in details[0]: HIS-403, not permitted. The HTTP status disagrees with the nested code too, arriving as 422 for what is an authorisation failure.

Read details[0].code before the top level one on any HIS- response, and show details[0].message to whoever is debugging. Acting on the outer code sends you to check your payload for a problem that is not there.

Codes​

Code, message and error name are as published. The action column reads the message text by a documented rule, and says Unclassified where the rule could not classify one.

Untagged codes​

The same collection, and the only source that recorded HTTP statuses.

UIDAI codes​

Codes from the Unique Identification Authority of India, passed through inside the message of ABDM-1204. More codes pass through than are listed here, so parse the message.

Every code above is recorded in the specification that owns it. The aggregated list across modules is at error codes.