Troubleshoot DigiLocker Consent and Document Errors
Trace DigiLocker errors through callback, token exchange, permissions, and retrieval. Use safe diagnostics to distinguish configuration errors from user choices.
Find the first failed stage in a DigiLocker request. Start with authorization and continue through token exchange, permission checks, document lookup, and integrity verification. The same message on the final screen can hide different causes.
Use your contract's error definitions and an internal request reference. The v2.4 specification documents errors separately by endpoint. Keep the stage alongside the status. Requester v2.4 specification
Route the failure by stage
| Observed stage | First check | Possible next step |
|---|---|---|
| Authorization rejects the request | Registered client, exact callback, and required fields | Correct the reviewed configuration |
| User denies consent | Valid callback and denial response | Offer the approved alternative |
| Token exchange rejects a code | Callback binding, verifier, code age, and environment | Start a fresh attempt after diagnosis |
| Document endpoint returns 403 | Returned permissions and approved document access | Review the contract and grant |
| List succeeds without the requested record | Issued record availability and permitted filters | Offer an approved manual review |
| Integrity check fails | Response bytes, MAC, and configured secret | Stop processing and investigate |
| Provider is unavailable | Dependency health and retry policy | Show a recoverable failure |
Treat these as diagnostic starting points. Verify the applicable endpoint and error details before assigning a cause.
Distinguish denied consent from an empty list
A person who declines has made a choice. An empty permitted list can also occur after a successful consent flow. A configuration failure may prevent the list request from succeeding at all.
For a synthetic support case, the user sees “We could not finish the check.” The internal event says the issued list request returned 403. The operator reviews the contract and granted permissions before advising the user to look for a missing licence.
Use language that fits the verified outcome. A missing record message should follow a valid lookup or an equivalent documented outcome.
Prepare a support handoff
- Record the internal verification reference.
- Record the environment and application name.
- Record the first failing stage.
- Record the bounded error code and approximate time.
- Describe the expected and observed behaviour.
- Send the summary through the approved support channel.
Exclude tokens, authorization codes, document contents, and full document URIs. Use a synthetic example when a screenshot would reveal a person's information.
Decide when a retry is safe
A fresh authorization may be necessary after a code is consumed or consent expires. A provider outage may allow a later retry under your documented policy. Keep retries of token cleanup separate from new verification attempts.
Inspect the state before retrying an action with side effects. Preserve the original reference so support can see the sequence. Consent and expiry boundaries.
Diagnose an integration with NamoID
NamoID engineers can help interpret a redacted failure stage and check your callback, scope, or approval assumptions. Share the environment, stack, and bounded error in Slack. Message the NamoID team in Slack