Data and Downloads
API Error Handling
This page provides guidelines for handling API errors within the application. While developing applications, AUAs need to decide how to handle the errors gracefully and provide resident/operator friendly messages. Simply showing the error on screen is not helpful. This document is an attempt to provide guidelines for doing better error handling.Â
Â
Following table describes API error codes, suggestion for how to handle it, possible message to user, and probable reasons for the error.
Â
Any other information regarding errors, please contact auth support team of UIDAI at authsupport@uidai.net.in.
| API Error Code | Description | Provision Required in the Application | Suggested Message to the User | Suggested instructions to the user | Probable Reasons |
| 100 | "Pi" (basic) attributes of demographic data did not match | User should be allowed to re-enter his/her personal information attributes like name, lname, gender, dob, dobt, age, phone, email whichever is used for authentication in application | Please re-enter your <name, lname, gender, dob, dobt, age, phone, email>. | Operator should re-enter correct details personal information as per the Aadhaar letter. Ensure correct Aadhaar Information is entered. | One or more personal information attributes not matching. |
| 200 | "Pa" attributes of demographic data did not match | User should be allowed to re-enter address fields | Please re-enter your <address details>. | Re-enter correct address as per the Aadhaar letter. Ensure correct Aadhaar Information is entered. | One or more address attributes not matching. |
| 300 | Biometric data did not match | Allow "n" retry attempts (configurable). Inform user of remaining attempts. | Please give your finger prints again. | Ensure correct Aadhaar number is entered. Clean fingers and place properly on scanner. | Poor fingerprint quality, scanner dust, wet fingers. |
| 310 | Duplicate fingers used in the request | Prompt user to provide distinct fingers | Please try again with distinct fingers. | Provide different fingers for two-finger authentication. | Same finger sent twice in the request. |
| 311 | Duplicate irises used in the request | Prompt user to provide distinct irises | Please try again with distinct irises. | Provide different irises for iris authentication. | Same iris sent twice in the request. |
| 312 | FMR and FIR cannot be mixed in the same transaction | Ensure no mixing of fingerprint image and minutiae records in a transaction | Technical Exception <No> | Contact technical helpdesk. | Cannot mix fingerprint image (FIR) and minutiae records (FMR). |
| 313 | Single FIR has multiple fingers | Prompt user to place a single finger at a time | Please try again placing single finger on device. | Place one finger at a time on the device. | FIR contains multiple finger images. |
| 314 | More than 10 FMR/FIR records in the request | Limit fingerprint records to a maximum of 10 | Technical Exception | Contact support. Ensure request does not exceed 10 finger records. | Authentication request exceeds 10 finger records. |
| 315 | More than 2 IIR records in the request | Limit iris records to a maximum of 2 | Technical Exception | Contact support. Ensure request does not exceed 2 iris records. | Authentication request exceeds 2 iris records. |
| 400 | OTP validation failed | Allow retry; provide option to regenerate OTP | Please provide correct OTP value. | Generate a new OTP if repeated failures occur. | Incorrect OTP entered or value mismatch in CIDR. |
| 401 | "Tkn" validation failed | Derive token value from network operator | Technical Exception | Contact support. Verify token details. | "Tkn" details do not match CIDR registration. |
| 500 | Invalid Skey encryption | Use configurable UIDAI-issued digital certificates | Technical Exception <No> | Contact technical helpdesk. Verify correct digital certificate is used for AES-256 encryption. | Wrong digital certificate used for AES-256 encryption. |
| 501 | Invalid "ci" attribute in Skey | Make "ci" value configurable | Technical Exception <> | Verify UIDAI certificate expiry date is properly specified. | Certificate expiry date not properly specified in "ci" attribute. |
| 502 | Invalid PID encryption | Test extensively with UIDAI test service | Technical Exception <No> | Ensure correct AES encryption implementation is used. | Incorrect AES encryption implementation. |
| 503 | Invalid HMAC encryption | Test extensively with UIDAI test service | Technical Exception <No> | Verify AES encryption and key usage are correct. | Incorrect AES encryption or mismatched session keys. |
| 504 | Session key re-initiation required | Provide full session key initiation capability | Technical Exception <No> | Try again. Session may have expired. | Session expired or session key out of sync. |
| 505 | Synchronized Skey not allowed | Use full skey scheme instead of synchronized scheme | Technical Exception <No> | Switch to full skey scheme. | AUA does not have SSK scheme privilege. |
| 510 | Invalid Auth XML format | Validate Auth XML before sending to CIDR | Technical Exception <No> | Use the latest recommended API version. | Non-compliance with Authentication API XML structure. |
| 511 | Invalid PID XML format | Validate PID XML structure before encryption | Technical Exception <No> | Use the latest recommended API version. | Non-compliance with PID XML format specification. |
| 520 | Invalid device — "tid" attribute value is incorrect | Set "tid" attribute to "public" for non-registered devices | Technical Exception <No> | Use "public" value only (lowercase) for "tid". | Incorrect "tid" attribute value in the request. |
| 521 | Invalid finger device code (fdc) | Obtain proper FDC code from certified vendor | Technical Exception <No> | Use certified FDC code obtained from the vendor. | FDC code not from a UIDAI-certified vendor. |
| 522 | Invalid iris device code (idc) | Obtain proper IDC code from certified vendor | Technical Exception <No> | Use certified IDC code obtained from the vendor. | IDC code not from a UIDAI-certified vendor. |
| 530 | Invalid authenticator code (AUA code) | Use registered AUA code in requests | Technical Exception <No> | Verify AUA code is registered with UIDAI. | Unregistered or mismatched AUA code used. |
| 540 | Invalid Auth XML version | Use a supported API version | Technical Exception <No> | Use the supported API version as recommended by UIDAI. | Unsupported or invalid API version specified. |
| 541 | Invalid PID XML version | Use a supported PID XML version | Technical Exception <No> | Use the supported PID XML version as recommended by UIDAI. | Unsupported PID element version specified. |
| 542 | AUA not authorized to use the ASA channel | Ensure AUA-ASA link exists in UIDAI portal | Ensure request is via authorized ASA. | Contact UIDAI helpdesk for ASA linkage. | No AUA-ASA linking configured in portal. |
| 543 | Sub-AUA not associated with AUA | Add Sub-AUA to correct parent AUA in portal | Ensure request is via associated AUA. | Contact UIDAI for Sub-AUA association. | Sub-AUA not added to the parent AUA. |
| 550 | Invalid "Uses" element attributes | Validate Uses tag attributes before sending request | Technical Exception <No> | Check "bt" attribute conditional usage rules. | Invalid attributes or conditional logic error in Uses element. |
| 561 | Request has expired (old timestamp) | Do not store Pid block; sync client date-time with IST | Verify device/client date-time synchronization. | Synchronize device with IST and resend the request. | Old request submitted or device date-time is behind current time. |
| 562 | Request has future timestamp | Sync client/server date-time with IST | Verify device/client date-time synchronization. | Synchronize device with IST and resend the request. | Device date-time is ahead of server time. |
| 563 | Duplicate request received | Prompt user to try again with a new request | Please submit your request again. | Send a new authentication request. | Identical request sent multiple times. |
| 564 | HMAC validation failed | Create HMAC using SHA-256 as defined in API | Technical Exception <No> | Verify HMAC algorithm implementation as per API specification. | Wrong HMAC calculation algorithm used. |
| 565 | License key has expired | Implement configurable license key management | Technical Exception <No> | Update the license key configuration. | Current license key has expired. |
| 566 | Invalid license key | Implement license key management feature | Technical Exception <No> | Verify license key validity with UIDAI. | License key is not valid. |
| 567 | Invalid input — unsupported characters in data | Add client-side and server-side validation for character encoding | Technical Exception <No> | Remove unsupported characters from Indian language fields. | Unsupported characters used in Indian language input fields. |
| 568 | Unsupported language specified | Restrict language selection to API-supported languages only | Technical Exception <No> | Select only a supported language as per UIDAI API specification. | Language value not in the supported language list. |
| 569 | Digital signature verification failed | Ensure end-to-end data integrity and security | Technical Exception <No> | Use a secure communication protocol. Do not modify XML after signing. | XML data modified after signing. |
| 570 | Invalid key info in digital signature | Store and manage certificate outside application code | Technical Exception <No> | Verify certificate validity and issuing authority. | Expired, invalid, or unauthorized digital certificate used. |
| 571 | PIN requires reset — default PIN not changed | Allow PIN reset before authentication usage | Please reset your PIN in the UIDAI update application. | Change default PIN via UIDAI client application. | Resident using unreset default PIN. |
| 572 | Invalid biometric position value | Validate "pos" attribute value against biometric type | Technical Exception <No> | Check that position value is valid for the biometric type used. | Position attribute does not match the biometric type. |
| 573 | Pi usage not allowed by license | Restrict Pi usage based on license authorization | Technical Exception <No> | Check AUA license for Pi usage authorization. | AUA license does not permit Pi usage. |
| 574 | Pa usage not allowed by license | Restrict Pa usage based on license authorization | Technical Exception <No> | Check AUA license for Pa usage authorization. | AUA license does not permit Pa usage. |
| 575 | Pfa usage not allowed by license | Restrict Pfa usage based on license authorization | Technical Exception <No> | Check AUA license for Pfa usage authorization. | AUA license does not permit Pfa usage. |
| 576 | FMR usage not allowed by license | Restrict FMR usage based on license authorization | Technical Exception <No> | Check AUA license for FMR usage authorization. | AUA license does not permit FMR usage. |
| 577 | FIR usage not allowed by license | Restrict FIR usage based on license authorization | Technical Exception <No> | Check AUA license for FIR usage authorization. | AUA license does not permit FIR usage. |
| 578 | IIR usage not allowed by license | Restrict IIR usage based on license authorization | Technical Exception <No> | Check AUA license for IIR usage authorization. | AUA license does not permit IIR usage. |
| 579 | OTP usage not allowed by license | Restrict OTP usage based on license authorization | Technical Exception <No> | Check AUA license for OTP usage authorization. | AUA license does not permit OTP usage. |
| 580 | PIN usage not allowed by license | Restrict PIN usage based on license authorization | Technical Exception <No> | Check AUA license for PIN usage authorization. | AUA license does not permit PIN usage. |
| 581 | Fuzzy matching not allowed by license | Restrict "ms" attribute usage per license | Technical Exception <No> | Check AUA license for fuzzy matching authorization. | AUA license does not permit fuzzy matching. |
| 582 | Local language usage not allowed by license | Restrict language options based on license | Technical Exception <No> | Use only authorized languages as per AUA license. | AUA license does not permit local language usage. |
| 584 | Invalid PIN code in Meta element | Validate PIN code value before submission | Technical Exception <No> | Use a valid PIN code from UIDAI-recognized system. | PIN code not in the valid values list. |
| 585 | Invalid Geo code in Meta element | Validate decimal latitude/longitude format | Technical Exception <No> | Use proper decimal format with 4-digit precision for geo coordinates. | Geo code does not match specification format. |
| 710 | Missing "Pi" data in PID block | Validate PID block structure before encryption | Technical Exception <No> | Ensure all required Pi data is included as per Uses specification. | Missing Pi data as specified in Uses element. |
| 720 | Missing "Pa" data in PID block | Validate PID block structure before encryption | Technical Exception <No> | Ensure all required Pa data is included as per Uses specification. | Missing Pa data as specified in Uses element. |
| 721 | Missing "Pfa" data in PID block | Validate PID block structure before encryption | Technical Exception <No> | Ensure all required Pfa data is included as per Uses specification. | Missing Pfa data as specified in Uses element. |
| 730 | Missing PIN data in PID block | Validate PID block structure before encryption | Technical Exception <No> | Ensure PIN data is included if specified in Uses element. | Missing PIN data as specified in Uses element. |
| 740 | Missing OTP data in PID block | Validate PID block structure before encryption | Technical Exception <No> | Ensure OTP data is included if specified in Uses element. | Missing OTP data as specified in Uses element. |
| 800 | Invalid biometric data | Review biometric device compliance with UIDAI standards | Technical Exception <No> | Verify ISO-compliant biometric templates are being used. | Non-ISO compliant or corrupted biometric templates. |
| 810 | Missing biometric data in PID block | Validate PID block structure before encryption | Technical Exception <No> | Ensure biometric data is included as per Uses specification. | Missing biometric data as specified in Uses element. |
| 811 | Biometric data not available in CIDR | Handle inactive biometric status and contact helpdesk | Biometric data not available in CIDR. Contact UIDAI. | Verify Aadhaar number and update biometrics via UIDAI. | Biometric not enrolled in resident's record in CIDR. |
| 812 | Best Finger Detection (BFD) not done | Initiate BFD application for the resident | Please proceed with the Best Finger Detection (BFD) process. | Complete the BFD process before authentication. | Resident has not completed Best Finger Detection process. |
| 820 | Missing "bt" attribute value in Uses element | Validate Uses element for "bt" attribute presence | Technical Exception <No> | Include a valid "bt" value in the Uses element. | Empty or missing "bt" attribute in Uses element. |
| 821 | Invalid "bt" attribute value in Uses element | Validate "bt" attribute against allowed values | Technical Exception <No> | Use valid "bt" attribute values as per API specification. | Invalid value specified in "bt" attribute. |
| 901 | No authentication data present in request | Validate that at least one authentication factor is included | Technical Exception <No> | Include at least one authentication factor (Demo, Pv, or Bios). | No Demo, Pv, or Bios data present in the request. |
| 902 | Invalid "dob" value format or out of range | Validate date-of-birth format and age range client-side | Please enter date of birth in the specified format. | Use YYYY or YYYY-MM-DD format. Age must be between 0 and 150 years. | Wrong date format or age value outside valid range. |
| 910 | Invalid "mv" attribute value in Pi element | Validate "mv" attribute value before request | Technical Exception <No> | Use a valid "mv" attribute value as per API specification. | Invalid "mv" value specified in Pi element. |
| 911 | Invalid "mv" attribute value in Pfa element | Validate "mv" attribute value before request | Technical Exception <No> | Use a valid "mv" attribute value as per API specification. | Invalid "mv" value specified in Pfa element. |
| 912 | Invalid "ms" (match score) attribute value | Validate "ms" attribute value before request | Technical Exception <No> | Use a valid "ms" attribute value as per API specification. | Invalid "ms" match score value specified. |
| 913 | Both Pa and Pfa elements present — mutually exclusive | Ensure Pa and Pfa are not sent in the same request | Pa and Pfa elements are mutually exclusive. Use only one. | Use either Pa or Pfa in the request, not both. | Both Pa and Pfa address elements present in the same request. |
| 930–939 | Technical server-side errors | Implement standard error handling and contact UIDAI tech support | Technical Exception <No> | Contact UIDAI technical support team. | Internal authentication server issues. |
| 940 | Unauthorized ASA channel used | Consult ASA for proper channel authorization | Technical Exception <No> | Verify ASA channel authorization with UIDAI. | Unauthorized ASA channel used in the request. |
| 941 | ASA channel not specified | Consult ASA and specify proper channel | Technical Exception <No> | Specify the proper ASA channel in the request. | ASA channel not specified in the request. |
| 980 | Unsupported option or development feature used in production | Review and remove all development features before production deployment | Technical Exception <No> | Remove development-only features from production build. | Development feature used in production environment. |
| 996 | Aadhaar number has been cancelled | Handle cancelled Aadhaar status and inform operator to re-enroll | This Aadhaar number has been cancelled. Resident should re-enroll. | Contact UIDAI helpline for re-enrollment. | Aadhaar number has been cancelled by UIDAI. |
| 997 | Aadhaar number is suspended or not active | Handle suspended Aadhaar status gracefully | Aadhaar status is not active. Please contact UIDAI. | Contact UIDAI helpline to resolve suspended status. | Aadhaar number is suspended or not active in CIDR. |
| 998 | Invalid Aadhaar number or data unavailable in system | Validate Aadhaar number format on client-side before submission | Please enter a correct Aadhaar number. | Retry with the correct 12-digit Aadhaar number. | Invalid Aadhaar number format or Aadhaar not found in CIDR. |
| 999 | Unknown error | Implement standard error handling for unknown errors | Technical Exception <No> | Contact authsupport@uidai.gov.in for assistance. | Unidentified error condition in the system. |
Â
Â
Testing Data and License Keys
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
UIDAI Certificate Details
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Sample Clients
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Content Information
Published on: 11 May 2026
Last Updated: 21 May 2026
Owner: Dev frontend
People also look for
- Documents
- Aadhaar Dashboard - Unique Identification Authority of India | Government of India
- Handbooks
- Videos - Unique Identification Authority of India | Government of India
- Annual Reports
Content Information
Published on: 11 May 2026
Last Updated: 21 May 2026
Owner: Dev frontend
