ABDM API — Error Handling Reference

Base URL

All endpoints are called with an Authorization: Bearer <idToken> header — except /auth_token, which issues that token.

https://asia-south1-psychic-city-328609.cloudfunctions.net/<endpoint>

• Default method is POST.
• /discharge_patient is PUT.
• /health_document is multipart/form-data (POST).

Error envelope (every non-2xx response)

Every error response uses the same JSON shape. There are no other error shapes.

{
  "message": "Human-readable summary of the failure",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      { "field": "patient.abhaAddress", "message": "The direct input of Abha Address or Abha number is not possible." }
    ]
  }
}

Example — non-validation error

{
  "message": "Patient not found",
  "error": {
    "code": "PATIENT_NOT_FOUND",
    "message": "Patient not found"
  }
}

Response headers

Every response — success or error — includes the same headers.

x-request-id

• If your request included an x-request-id header, its value is echoed back unchanged.
• Otherwise a new UUID is generated.
• The value lives in the header only — never inside the JSON body.

Send an x-request-id on every request and log the request/response pair against it. When escalating an issue to Nice HMS support, include this value — it correlates to the server-side log of the full (unredacted) error.

Access-Control-Allow-Origin

Every response includes Access-Control-Allow-Origin: *, so the API can be called directly from browser-based clients (CORS is enabled for all origins). No per-origin allow-list is required on the integrator's side.

Error code taxonomy

Match on error.code — these are stable strings.

HTTP status code summary

Validation semantics (important)

1. Extra / unknown fields are ignored (stripped), not rejected. You will not get an error for sending fields the API doesn't know about.
2. Validation runs before auth. A request that is both unauthenticated and has an invalid body returns 400 VALIDATION_ERROR first (auth is checked after body validation).
3. Field paths in details[].field use dot notation, e.g. patient.firstName, doctorDetails.0.doctorGcpId, patient.dob.
4. Curated messages only. Responses never leak stack traces, SQL, DB error text, GCP FHIR paths/IDs, or raw ABDM payloads. The full unredacted cause is logged server-side against the x-request-id.

Field enum values

Some VALIDATION_ERROR messages name the rejected field but not its accepted values — e.g. details[].message is just "Invalid category". The accepted values for each enum field are listed in that endpoint's request table; see ABDM API — Documents.

For example, /diagnostic_report category accepts:

Hematology · Biochemistry · Microbiology · Radiology · Others

Shared error codes (every authenticated route)

The following codes are present on every authenticated route:

VALIDATION_ERROR (400) · UNAUTHORIZED (401) · SUBSCRIPTION_EXPIRED (403) · DB_ERROR (500) · INTERNAL_ERROR (500)

Each endpoint's documentation lists these shared codes + its own additional codes.

Per-route error reference

Where a route says "patientNeeds", the body must include at least one of abhaAddress (string) or patientId (number). Omitting both yields 400 VALIDATION_ERROR with the message "Either abhaAddress or patientId is required".

The table lists each route's additional codes — the ones on top of the shared codes. (/auth_token is public and skips the subscription check.)

Not covered here

• /uhi and /uhi/whatsapp follow the UHI protocol (search/init/confirm/cancel/status), which has its own acknowledgement and error format — documented separately, not via this envelope.

Quick reference — which code for which mistake

Troubleshooting: PATIENT_NOT_FOUND (404)

PATIENT_NOT_FOUND means no patient matched the identifier you sent for the organization tied to your bearer token. Common causes, in order of likelihood:

1. patientId sent as a string, not a number. patientId must be a JSON number — 1250, not "1250". A quoted value can fail the lookup even when the digits look right.
2. abhaAddress is a placeholder, not a real address. A literal value like "{{abhaAddress}}" (an unresolved template variable) matches no patient. Send the actual ABHA address (e.g. savitribilagi@sbx), or omit abhaAddress entirely when using patientId.
3. Wrong identifier for the patient type. A non-ABHA patient (created via /create_patient) has an empty abhaAddress — it can only be fetched by patientId, not by ABHA address. Conversely an ABHA patient is fetched by abhaAddress.
4. Organization scoping. A patient created under one organization is not visible to a different organization's token. Use the token of the org that registered the patient.
5. Sending both identifiers. Validation accepts either, but the lookup precedence when both are supplied is undefined — send exactly one (the one you intend to match) so a bad abhaAddress can't mask a valid patientId.

Confirm the identifier before creating a visit by fetching it with /patient_by_id or /patient_by_abhaAddress. If it resolves there but a visit endpoint still returns PATIENT_NOT_FOUND, escalate with the x-request-id — the server log holds the full unredacted cause.

Troubleshooting: the link token (LINK_TOKEN_RATE_LIMITED 429 / LINK_TOKEN_MISSING 502)

Document endpoints file a care context against an ABDM link token before pushing. ABDM issues at most 3 new link tokens per ABHA address per 24 hours; a token is valid about 6 months and supports unlimited document sends. So a token should be generated once and reused, not re-created per document.

Guidance:

1. Generate once, reuse. A link token lasts ~6 months — generate it at patient/ABHA linking time and keep it, rather than requesting a new one for each document.
2. Don't retry a 429 in a loop. Each retry counts against the same daily cap and keeps you blocked; wait out the 24 h window.
3. A 429 is not a payload problem. Nothing in your request body caused it, so changing fields won't help.

Troubleshooting: 401 UNAUTHORIZED

401 means the bearer token is missing, malformed, expired, or not mapped to an organization.

1. Header format. Send Authorization: Bearer <idToken> — the literal word Bearer, one space, then the token.
2. Expired token. Tokens are short-lived (15–30 minutes). There is no refresh endpoint — call /auth_token again with your email/password and retry.
3. Token from the wrong organization. A token is scoped to one organization. Using it against another organization's data returns 401.
4. Bad credentials on /auth_token. If /auth_token itself returns 401, the email or password is wrong — verify them or request a reset (see Getting integration credentials).

Troubleshooting: 400 VALIDATION_ERROR

400 means the request body failed schema validation. error.details names each failed field as { field, message } (dot notation, e.g. patient.dob). Common causes:

1. Missing required field — for example date on a visit/document endpoint, doa on /admit_patient, dod on /discharge_patient, or patient.dob on /create_patient. The message is usually "Required".
2. Wrong type — patientId must be a JSON number (1250, not "1250").
3. Unresolved template placeholder — a literal "{{abhaAddress}}" sent instead of a real value fails validation.
4. Wrong enum value — the message names the field but not the accepted values; see the field-enum table below.
5. Upload problems on /health_document — unsupported type, missing file, or a PDF combined with images (400); a file over 5 MB (413).

Validation runs before authentication, so a request that is both unauthenticated and malformed returns 400, not 401.

Troubleshooting: 500 DB_ERROR / 500 INTERNAL_ERROR

Both are server-side failures. Nothing in your request body caused them, so changing fields will not help.

• Retry with backoff. Retry a 500 up to 2–3 times with exponential backoff (for example 1s, 2s, 4s).
• Do not retry 400, 401, 403, 404, 409, 410, or 413 — those need a fix, not a retry.
• Escalate with x-request-id. If a 500 persists, send the request's x-request-id to Nice HMS support (admin@nicehms.com) — it maps to the full unredacted server-side log.

Field enums in validation errors

An enum VALIDATION_ERROR names the rejected field but not its accepted values. Accepted values live in each endpoint's request table:

Date and time fields

Timestamp fields use ISO 8601 — e.g. "2023-05-08T19:21:23.918Z" (see the examples in each endpoint). patient.dob is the exception: YYYY-MM-DD (date only, no time).

A VALIDATION_ERROR of { "field": "date", "message": "Required" } means you hit one of the endpoints in the first row and omitted date.