abdm-debugging

name	abdm-debugging
description	Diagnose and fix ABDM Connect integration failures - error code decoding (ABDM-xxxx, MIS-xxxx, EKA-xxxx), webhook non-delivery, OTP/rate-limit issues, linking failures, consent stuck states, and FHIR rejections. Use when the user reports any ABDM error, a failing test, "webhook not received", "linking stuck", "consent not granted", "data not arriving", or asks to debug the integration.

Debugging ABDM Connect

Method (always in this order)

1. Reproduce with a minimal curl against sandbox; capture full request/response + headers + txn/request IDs.
2. Classify: 4xx = your request (fix schema/state), 5xx with ABDM-code = gateway/NHA side (often transient — retry with backoff, then escalate), no response = network/webhook plumbing.
3. Check state preconditions — most "mystery" failures are sequence violations (see table).
4. Fix, re-run the failing test from abdm-testing, then the full suite for that milestone.

Error decode table (high-frequency)

Full table: fetch /api-reference/user-app/abdm-connect/errors.md.

Code	Meaning	Likely fix
MIS-1013	Wrong OTP	user input; surface cleanly, allow retry
MIS-1026	Transaction not found for UUID	txn_id expired/mismatched — restart flow; don't cache txn_id across sessions
ABDM-1100	OTP flood / max attempts	enforce client-side cooldown; retry after 30 min
ABDM-1027	Blocked 24h	too many failures; back off, warn user
ABDM-1013 / 1051	Invalid ABHA number/address	validate format before calling (14-digit; address regex ^[a-zA-Z0-9._]+@[a-z]+$)
ABDM-1012	No records for ABHA address	expected on fresh ABHA; not an error path
ABDM-1035	Invalid HIP ID / OTP mismatch (dual use)	facility not onboarded (M4 gap) or wrong X-Hip-Id header
ABDM-1026 / 1038	Invalid link token / token-address mismatch	re-auth the user session; don't reuse link tokens across ABHAs
ABDM-1061 / 1062	Consent expired / not granted	check consent state machine before fetching
ABDM-1101	ABHA address exists	run suggest-abha-address, pick unique
ABDM-1022	Too many requests	rate limit — exponential backoff
EKA-1001/1002	Mobile already claimed	account-claim conflict; direct user to login instead of create
ABDM-1028 / 1033 / 1401 / 1402	HIP/HIU unavailable, no ack	counterparty down (common in sandbox); retry later, not your bug

Webhook not received — checklist

1. Tunnel/URL still alive and registered? (curl it from outside)
2. Endpoint returns 2xx fast (<5s)? Slow handlers get dropped/retried.
3. Event type actually expected? (e.g. no hip_data_fetch when Eka stores your data — that's correct behaviour, not a bug)
4. Check server access logs — delivered-but-crashed is the most common case.
5. Signature verification rejecting valid calls? Log the raw body before verification in debug mode.

Async flow stuck

• Linking stuck pending: confirm 202 was received, then webhook status; verify facility onboarded and X-Hip-Id correct.
• Consent stuck "requested": patient never approved on PHR — in sandbox, approve via consent-approve API with a user token.
• Data never arrives after grant: HIP side down (sandbox HIPs flake), or your HIU keyset was never registered (hiu-keys).

FHIR rejections

Validate locally first (abdm-fhir skill). Common: missing Composition, non-urn fullUrls, missing ABHA identifier on Patient, wrong hi_type vs bundle content, timestamps not ISO 8601.

Escalation

If a gateway-side error persists >1h with correct requests: collect request-id, txn-id, timestamps, endpoint, and payload (redact PII) and contact Eka support / your Eka SPOC. Never retry OTP-generating endpoints in a loop.

On-demand debug report (give this to Eka support)

When the user asks for this directly ("give me everything Eka needs to debug this", "debug report", "escalation packet", or similar) — or once escalation is warranted per the rule above — produce it immediately, don't just describe that one could be made. Pull every field from the actual failing request/response you reproduced (or the client's logs if you can't reproduce live); never invent a value you don't have evidence for, say "not captured" instead.

Format:

## ABDM Debug Report — <milestone, e.g. M2 care-context linking>

- Timestamp (request): <ISO 8601, from the actual failing call>
- Timestamp (report generated): <ISO 8601, now>
- Environment: sandbox (api.dev.eka.care) | prod (api.eka.care)
- client_id: <EC_...>
- hip_id: <if applicable to this flow>
- transaction_id / txn_id: <if applicable>
- request_id: <from response headers/body, if present>
- Endpoint: <METHOD /path>
- Error code(s): <ABDM-xxxx / MIS-xxxx / EKA-xxxx + HTTP status>

### Reproduction (curl)
​```bash
curl -X <METHOD> '<full URL>' \
  -H 'auth: <REDACTED>' \
  -H 'X-Hip-Id: <hip_id if applicable>' \
  -H 'X-Pt-Id: <if applicable>' \
  -d '<request body, PII fields redacted>'
​```

### Response received
​```
<full response body + relevant response headers>
​```

### What's already been ruled out
<sequence preconditions checked, retries attempted, anything from the Method/Classify steps above>

Redaction rules (non-negotiable, same as everywhere else in this plugin): never include client_secret, access/refresh tokens, Aadhaar numbers, OTPs, or full patient mobile numbers in the curl or response — replace with <REDACTED>. client_id, hip_id, ABHA address/number, and transaction/request IDs are safe to include (Eka support needs them to look anything up).