Error Codes

Complete reference of AD Unlock error codes.

Connection Errors

Code	Message	Cause	Solution
`CONN_001`	Gateway unreachable	Network issue	Check firewall, allow outbound 443
`CONN_002`	SSL handshake failed	SSL inspection	Add bypass for api.adunlock.me
`CONN_003`	Certificate invalid	Expired/wrong cert	Renew certificates
`CONN_004`	Authentication failed	Wrong tenant/connector ID	Verify IDs in config
`CONN_005`	Connection timeout	Network latency	Check network path

LDAP Errors

Code	Message	Cause	Solution
`LDAP_001`	Bind failed	Wrong credentials	Verify service account
`LDAP_002`	Server unreachable	DC not reachable	Check network/firewall
`LDAP_003`	TLS handshake failed	LDAPS not enabled	Enable LDAPS on DC
`LDAP_004`	Permission denied	Missing delegation	Re-run permissions script
`LDAP_005`	Object not found	Wrong DN	Verify base_dn and OUs
`LDAP_006`	Constraint violation	Password policy	Check AD password policy
`LDAP_007`	Unwilling to perform	Secure connection required	Use LDAPS (port 636)

Request Errors

Code	Message	Cause	Solution
`REQ_001`	User not enrolled	Phone not registered	Enroll user
`REQ_002`	User not found in AD	User doesn’t exist	Verify AD user
`REQ_003`	User not in allowed OU	OU not configured	Add OU to allowed_ous
`REQ_004`	User in denied group	Member of blocked group	Remove from group or policy
`REQ_005`	Request blocked	Risk too high	Manual approval required
`REQ_006`	Rate limit exceeded	Too many requests	Wait and retry

Verification Errors

Code	Message	Cause	Solution
`OTP_001`	Code expired	OTP older than 5 min	Request new code
`OTP_002`	Code invalid	Wrong code entered	Enter correct code
`OTP_003`	Too many attempts	3+ failed attempts	Start new session
`OTP_004`	Email send failed	Email delivery issue	Check email config

Configuration Errors

Code	Message	Cause	Solution
`CFG_001`	Config file not found	Missing config.yaml	Create config file
`CFG_002`	Invalid YAML	Syntax error	Validate YAML
`CFG_003`	Missing required field	Required option missing	Add required field
`CFG_004`	Invalid value	Wrong value type	Check documentation
`CFG_005`	Certificate not found	Cert file missing	Download bundle

API Errors

Code	HTTP	Message	Cause
`API_001`	401	Unauthorized	Invalid/missing token
`API_002`	403	Forbidden	Insufficient permissions
`API_003`	404	Not found	Resource doesn’t exist
`API_004`	429	Rate limited	Too many requests
`API_005`	500	Internal error	Server issue

Troubleshooting Steps

For Connection Errors

Check network connectivity
Verify firewall rules
Test with diagnostic script
Check connector logs

For LDAP Errors

Test LDAPS with PowerShell
Verify service account
Check delegated permissions
Review DC configuration

For Request Errors

Verify user enrollment
Check policy configuration
Review risk factors
Check audit logs

Last updated on January 26, 2026

Configuration Options Glossary