L3S DRM Developer Guide
Error Codes Reference
This page documents all error codes returned by the L3DRM authentication system. These codes appear in session logs and help diagnose authentication issues.
Error Code Categories
| Prefix | Category | HTTP Status | Description |
|---|---|---|---|
AUTH_ | Authentication | 401 | Request authentication failures (credentials, API key, payload) |
AUTHZ_ | Authorization | 403 | Access control failures (key status, user blocked, permissions) |
RATE_ | Rate Limiting | 429 | Too many failed authentication attempts |
PRE_ | Pre-Check | 403 | Pre-validation failures before full authentication (API key revoked, user blocked) |
SRV_ | Server | 5xx | Server-side errors (internal errors, database issues) |
TMPR_ | Client-Side | N/A | Local tamper detection errors raised by the WASM module (file hash issues) |
Authentication Errors (HTTP 401)
These errors occur when the request cannot be authenticated.
| Code | Description | Trigger Condition | Message |
|---|---|---|---|
AUTH_001 | Invalid user agent | The DRM library is not properly integrated - User-Agent must start with "KittyHawk" | Authentication failed |
AUTH_002 | Missing credentials | The DRM request is missing required encrypted payload fields | Authentication failed |
AUTH_003 | Invalid Client API key | The Client API key in the WASM build is invalid or not configured in the dashboard | Invalid or incorrect key |
AUTH_004 | Inactive Client API key | The Client API key has been deactivated - the product needs to be updated | Please update this product |
AUTH_005 | Malformed payload | Payload decryption failed - possible tampering or corrupted DRM library | Authentication failed |
Authorization Errors (HTTP 403)
These errors occur when the request is authenticated but access is denied.
| Code | Description | Trigger Condition | Message |
|---|---|---|---|
AUTHZ_001 | Activation key not found | The activation key doesn't exist for this project | Invalid or incorrect key |
AUTHZ_002 | Activation key disabled | The activation key has been disabled in the dashboard | Key is inactive |
AUTHZ_003 | Activation key expired | The activation key's expiry date has passed | Key has expired |
AUTHZ_004 | User blocked | This Xbox/MSFS username has been blocked by the project owner | Access denied |
AUTHZ_005 | Invalid WASM hash | The WASM binary hash doesn't match an approved version - possible tampering or outdated build | Access denied |
AUTHZ_006 | Missing WASM hash | Hash verification is required but the client didn't provide a file hash | Access denied |
AUTHZ_007 | User switch cooldown | User changed too recently - wait ~15 minutes between user switches on the same key | Access denied |
AUTHZ_008 | Activation key required | This project requires an activation key - store/keyless authentication is disabled | Access denied |
Pre-Check Errors (HTTP 403)
These errors occur during the pre-validation step, before the full authentication flow runs.
| Code | Description | Trigger Condition | Message |
|---|---|---|---|
PRE_001 | API key revoked | The Client API key has been revoked or is inactive - checked during the pre-validation step | Access denied |
PRE_002 | User blocked (pre-check) | This Xbox/MSFS username has been blocked - checked during the pre-validation step | Access denied |
Rate Limiting Errors (HTTP 429)
These errors protect against brute force and credential stuffing attacks.
| Code | Description | Trigger Condition | Message |
|---|---|---|---|
RATE_001 | Activation key rate limited | Too many failed attempts with this key (10+ failures in 10 minutes) | Too many requests |
RATE_002 | User rate limited | Too many failed attempts for this user (5+ failures in 10 minutes) | Too many requests |
Rate Limiting Details:
- RATE_001 (Per-Key): 10 failed attempts within 10 minutes
- RATE_002 (Per-User): 5 failed attempts within 10 minutes
Failed attempts are counted from the sessions table where
auth_response != '200'.
Server Errors (HTTP 5xx)
These errors indicate server-side issues.
| Code | HTTP Status | Description | Trigger Condition |
|---|---|---|---|
SRV_001 | 500 | Internal server error | Unexpected server error - please try again or contact support |
SRV_002 | 503 | Database unavailable | Database is temporarily unavailable - please try again in a few moments |
Client-Side Errors (File Hash Verification)
These errors are raised locally by the WASM module when file hash verification fails. They do not involve a server request. If autoAbort is enabled, the module will crash; otherwise, the onTamper callback is called.
| Code | Description | Trigger Condition |
|---|---|---|
TMPR_019 | File hash mismatch | A registered file's hash does not match the expected value - the file may have been modified after release, or the hash was not updated after editing the file |
TMPR_020 | WASM path empty | The .wasmPath() builder option is empty or was not set - this is required for file hash verification |
TMPR_021 | File hash computation failed | The DRM module could not read or compute the hash of a registered file - check that the file path is correct and the file exists in the package |
Tip: Enable
.debug(true)in your builder (in a debug build only) to see which file failed hash verification in the MSFS console.
Authentication Flow
The auth4 endpoint validates requests in this order:
- User-Agent validation →
AUTH_001 - Required fields check →
AUTH_002 - API key lookup →
AUTH_003/AUTH_004 - Payload decryption →
AUTH_005 - Activation key lookup →
AUTHZ_001 - Rate limiting →
RATE_001/RATE_002 - Key status check →
AUTHZ_002/AUTHZ_003 - User block check →
AUTHZ_004 - File hash validation →
AUTHZ_005/AUTHZ_006 - User switch cooldown →
AUTHZ_007 - Success → HTTP 200
Tip: When troubleshooting authentication issues, check the error code in the session history to identify exactly where the authentication failed.