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"
  }
}

Request correlation — x-request-id header

Every response includes an x-request-id header:

• 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.

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.

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