Error Messages & Codes #

Back to docs index | Back to project README

MBKAuthe provides a comprehensive error messaging system with standardized error codes and user-friendly messages.

Overview #

The error messaging system provides:

Standardized Error Codes: Consistent error codes across all operations
User-Friendly Messages: Clear, actionable error messages for end users
Developer Context: Detailed error information for logging and debugging
Helpful Hints: Guidance on how to resolve errors
Structured Responses: Consistent error response format
Dynamic Documentation: Error code page at /mbkauthe/ErrorCode auto-generates from lib/utils/errors.js

Dynamic Error Documentation #

The error code documentation page (/mbkauthe/ErrorCode) is automatically generated from the lib/utils/errors.js file. This ensures the documentation is always in sync with the actual error codes in the system.

Adding New Errors #

To add a new error code:

Define the error code in ErrorCodes enum:

javascript

export const ErrorCodes = {
    // ... existing codes
    YOUR_NEW_ERROR: 1400,
};

Add error details to ErrorMessages object:

javascript

export const ErrorMessages = {
    // ... existing messages
    [ErrorCodes.YOUR_NEW_ERROR]: {
        message: "Internal message for logging",
        userMessage: "User-friendly error message",
        hint: "Helpful tip to resolve the issue"
    },
};

Include in category array in misc.js route handler:

javascript

const categories = [
    // ... existing categories
    {
        name: "Your Category Name",
        range: "1400-1499",
        codes: [1400, 1401, 1402] // Add your new codes here
    }
];

The error code page will automatically display your new error without any additional changes.

Error Code Ranges #

Range	Category	Example
600-699	Authentication	Invalid credentials, account inactive
700-799	Two-Factor Authentication	Invalid 2FA token, 2FA not configured
800-899	Session Management	Session expired, invalid session
900-999	Authorization	Insufficient permissions, role not allowed
1000-1099	Input Validation	Missing fields, invalid format
1100-1199	Rate Limiting	Too many requests
1200-1299	Server Errors	Internal error, database error
1300-1399	OAuth	GitHub not linked, OAuth failed

Error Codes Reference #

Authentication Errors (600-699) #

`601 - INVALID_CREDENTIALS` #

General authentication failure.

javascript

{
    errorCode: 601,
    message: "The username or password you entered is incorrect. Please try again.",
    hint: "Check your spelling and make sure Caps Lock is off"
}

`602 - USER_NOT_FOUND` #

User account doesn't exist.

javascript

{
    errorCode: 602,
    message: "We couldn't find an account with that username.",
    hint: "Please check the username and try again"
}

`603 - INCORRECT_PASSWORD` #

Password doesn't match.

javascript

{
    errorCode: 603,
    message: "The password you entered is incorrect.",
    hint: "Make sure you're using the correct password for this account"
}

`604 - ACCOUNT_INACTIVE` #

User account is deactivated.

javascript

{
    errorCode: 604,
    message: "Your account has been deactivated.",
    hint: "Please contact your administrator to reactivate your account"
}

`605 - APP_NOT_AUTHORIZED` #

User not authorized for this application.

javascript

{
    errorCode: 605,
    message: "You don't have permission to access this application.",
    hint: "Contact your administrator if you believe this is an error"
}

2FA Errors (700-799) #

`701 - TWO_FA_REQUIRED` #

2FA verification needed.

`702 - TWO_FA_INVALID_TOKEN` #

Invalid 2FA code.

`703 - TWO_FA_NOT_CONFIGURED` #

2FA not set up.

`704 - TWO_FA_EXPIRED` #

2FA code has expired.

Session Errors (800-899) #

`801 - SESSION_EXPIRED` #

Session has expired.

`802 - SESSION_INVALID` #

Session is no longer valid.

`803 - SESSION_NOT_FOUND` #

No active session found.

Authorization Errors (900-999) #

`901 - INSUFFICIENT_PERMISSIONS` #

User lacks required permissions.

`902 - ROLE_NOT_ALLOWED` #

User's role doesn't have access.

Input Validation Errors (1000-1099) #

`1001 - MISSING_REQUIRED_FIELD` #

Required field not provided.

`1002 - INVALID_USERNAME_FORMAT` #

Username format is invalid.

`1003 - INVALID_PASSWORD_LENGTH` #

Password doesn't meet length requirements.

`1004 - INVALID_TOKEN_FORMAT` #

Token format is incorrect.

`1005 - INVALID_AUTH_TOKEN` #

The provided API token is invalid.

`1006 - API_TOKEN_EXPIRED` #

The provided API token has expired.

`1007 - TOKEN_SCOPE_INSUFFICIENT` #

Token scope doesn't allow the requested operation.

javascript

{
    errorCode: 1007,
    message: "This API token doesn't have permission for this operation.",
    hint: "Use a token with 'write' scope or create a new one with appropriate permissions"
}

Rate Limiting (1100-1199) #

`1101 - RATE_LIMIT_EXCEEDED` #

Too many requests in time window.

Server Errors (1200-1299) #

`1201 - INTERNAL_SERVER_ERROR` #

General server error.

`1202 - DATABASE_ERROR` #

Database operation failed.

`1203 - CONFIGURATION_ERROR` #

System configuration issue.

OAuth Errors (1300-1399) #

`1301 - GITHUB_NOT_LINKED` #

GitHub account not linked.

`1302 - GITHUB_AUTH_FAILED` #

GitHub authentication failed.

`1303 - OAUTH_STATE_MISMATCH` #

OAuth state verification failed.

API Usage #

Import Error Utilities #

javascript

import { 
    ErrorCodes, 
    ErrorMessages, 
    getErrorByCode, 
    createErrorResponse, 
    logError 
} from 'mbkauthe';

Get Error Details #

javascript

import { getErrorByCode, ErrorCodes } from 'mbkauthe';

const error = getErrorByCode(ErrorCodes.INVALID_CREDENTIALS);

console.log(error);
// {
//     errorCode: 601,
//     message: "Invalid username or password",
//     userMessage: "The username or password you entered is incorrect...",
//     hint: "Check your spelling and make sure Caps Lock is off"
// }

Create Error Response #

javascript

import { createErrorResponse, ErrorCodes } from 'mbkauthe';

app.post('/login', async (req, res) => {
    // ... authentication logic
    
    if (!authenticated) {
        return res.status(401).json(
            createErrorResponse(401, ErrorCodes.INVALID_CREDENTIALS)
        );
    }
});

// Response:
// {
//     success: false,
//     statusCode: 401,
//     errorCode: 601,
//     message: "The username or password you entered is incorrect...",
//     hint: "Check your spelling and make sure Caps Lock is off",
//     timestamp: "2025-12-03T12:00:00.000Z"
// }

Add Custom Data #

javascript

import { createErrorResponse, ErrorCodes } from 'mbkauthe';

return res.status(403).json(
    createErrorResponse(403, ErrorCodes.APP_NOT_AUTHORIZED, {
        appName: 'Admin Panel',
        requiredRole: 'superadmin'
    })
);

// Response includes custom data:
// {
//     success: false,
//     statusCode: 403,
//     errorCode: 605,
//     message: "You don't have permission to access this application.",
//     hint: "Contact your administrator if you believe this is an error",
//     timestamp: "2025-12-03T12:00:00.000Z",
//     appName: "Admin Panel",
//     requiredRole: "superadmin"
// }

Log Errors #

javascript

import { logError, ErrorCodes } from 'mbkauthe';

// Log error with context
logError('Login attempt', ErrorCodes.INVALID_CREDENTIALS, {
    username: 'john.doe',
    ip: req.ip,
    userAgent: req.headers['user-agent']
});

// Console output:
// [mbkauthe] Login attempt: {
//     errorCode: 601,
//     message: 'Invalid username or password',
//     username: 'john.doe',
//     ip: '192.168.1.1',
//     userAgent: 'Mozilla/5.0...',
//     timestamp: '2025-12-03T12:00:00.000Z'
// }

Error Response Format #

All error responses follow this structure:

typescript

{
    success: false,
    statusCode: number,
    errorCode: number,
    message: string,        // User-friendly message
    hint: string,           // How to resolve the error
    timestamp: string,      // ISO 8601 timestamp
    ...customFields         // Optional custom data
}

Client-Side Error Handling #

JavaScript Example #

javascript

async function login(username, password) {
    try {
        const response = await fetch('/mbkauthe/api/login', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ username, password })
        });
        
        const data = await response.json();
        
        if (!response.ok) {
            // Handle error based on error code
            switch (data.errorCode) {
                case 601: // INVALID_CREDENTIALS
                case 602: // USER_NOT_FOUND
                case 603: // INCORRECT_PASSWORD
                    showError('Invalid username or password', data.hint);
                    break;
                    
                case 604: // ACCOUNT_INACTIVE
                    showError('Account deactivated', data.hint);
                    break;
                    
                case 605: // APP_NOT_AUTHORIZED
                    showError('Access denied', data.hint);
                    redirectToHome();
                    break;
                    
                case 1003: // INVALID_PASSWORD_LENGTH
                    showFieldError('password', data.message, data.hint);
                    break;
                    
                default:
                    showError(data.message, data.hint);
            }
            return;
        }
        
        // Handle successful login
        if (data.two_factor_required) {
            redirectTo2FA();
        } else {
            redirectToDashboard();
        }
        
    } catch (error) {
        showError('Network error', 'Please check your connection and try again');
    }
}

function showError(message, hint) {
    const errorDiv = document.getElementById('error-message');
    errorDiv.innerHTML = `
        <div class="error">
            <strong>${message}</strong>
            <p>${hint}</p>
        </div>
    `;
}

React Example #

jsx

import { ErrorCodes } from 'mbkauthe';

function LoginForm() {
    const [error, setError] = useState(null);
    
    const handleLogin = async (e) => {
        e.preventDefault();
        
        try {
            const response = await fetch('/mbkauthe/api/login', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({ username, password })
            });
            
            const data = await response.json();
            
            if (!response.ok) {
                setError({
                    code: data.errorCode,
                    message: data.message,
                    hint: data.hint
                });
                return;
            }
            
            // Success handling...
            
        } catch (err) {
            setError({
                message: 'Network error',
                hint: 'Please check your connection'
            });
        }
    };
    
    return (
        <form onSubmit={handleLogin}>
            {error && (
                <div className="alert alert-danger">
                    <strong>{error.message}</strong>
                    {error.hint && <p className="hint">{error.hint}</p>}
                </div>
            )}
            {/* Form fields... */}
        </form>
    );
}

Custom Error Messages #

You can create custom error responses while maintaining the standard format:

javascript

import { createErrorResponse, sessVal } from 'mbkauthe';

app.post('/custom-action', sessVal, async (req, res) => {
    try {
        // Your logic...
        
        if (someCondition) {
            return res.status(400).json(
                createErrorResponse(400, 9999, {
                    message: "Custom error message",
                    hint: "How to fix this issue",
                    additionalData: "Extra context"
                })
            );
        }
        
    } catch (error) {
        return res.status(500).json(
            createErrorResponse(500, 1201)
        );
    }
});

Best Practices #

Use Error Codes: Always use predefined error codes for consistency
Log Errors: Use logError() for server-side logging
User-Friendly Messages: Display message to users, not raw error codes
Provide Hints: Show hint to guide users on resolution
Don't Expose Internals: Avoid exposing system details in production
Handle All Cases: Have fallback error handling for unexpected errors
Client-Side Validation: Validate input before sending to prevent unnecessary errors
Structured Logging: Include context (username, IP, etc.) in logs

Security Considerations #

Generic Messages: For authentication, use generic messages to avoid user enumeration
Rate Limiting: Implement rate limiting to prevent brute force
Logging: Log all authentication failures for security monitoring
Error Details: Only expose detailed errors in development, not production
Sensitive Data: Never include passwords or tokens in error logs

Examples #

javascript

router.post('/mbkauthe/api/login', async (req, res) => {
    const { username, password } = req.body;
    
    try {
        // Validation
        if (!username || !password) {
            logError('Login', ErrorCodes.MISSING_REQUIRED_FIELD);
            return res.status(400).json(
                createErrorResponse(400, ErrorCodes.MISSING_REQUIRED_FIELD)
            );
        }
        
        if (username.length > 255) {
            logError('Login', ErrorCodes.INVALID_USERNAME_FORMAT, { username });
            return res.status(400).json(
                createErrorResponse(400, ErrorCodes.INVALID_USERNAME_FORMAT)
            );
        }
        
        if (password.length < 8) {
            logError('Login', ErrorCodes.INVALID_PASSWORD_LENGTH);
            return res.status(400).json(
                createErrorResponse(400, ErrorCodes.INVALID_PASSWORD_LENGTH)
            );
        }
        
        // Authentication
        const user = await findUser(username);
        
        if (!user) {
            logError('Login', ErrorCodes.USER_NOT_FOUND, { username });
            // Use generic message for security
            return res.status(401).json(
                createErrorResponse(401, ErrorCodes.INVALID_CREDENTIALS)
            );
        }
        
        if (!await verifyPassword(password, user.password)) {
            logError('Login', ErrorCodes.INCORRECT_PASSWORD, { username });
            return res.status(401).json(
                createErrorResponse(401, ErrorCodes.INCORRECT_PASSWORD)
            );
        }
        
        if (!user.active) {
            logError('Login', ErrorCodes.ACCOUNT_INACTIVE, { username });
            return res.status(403).json(
                createErrorResponse(403, ErrorCodes.ACCOUNT_INACTIVE)
            );
        }
        
        // Success
        res.json({ success: true, message: 'Login successful' });
        
    } catch (error) {
        console.error(`[mbkauthe] Login error:`, error);
        return res.status(500).json(
            createErrorResponse(500, ErrorCodes.INTERNAL_SERVER_ERROR)
        );
    }
});

Support #

For questions about error handling:

GitHub Issues
Email: support@mbktech.org

Previous Topic Operational & Rate Limits Next Topic Code Examples & Recipes

Suggest an edit on GitHub Back to top

Error Codes Directory

Error Messages & Codes #

Overview #

Dynamic Error Documentation #

Adding New Errors #

Error Code Ranges #

Error Codes Reference #

Authentication Errors (600-699) #

601 - INVALID_CREDENTIALS #

602 - USER_NOT_FOUND #

603 - INCORRECT_PASSWORD #

604 - ACCOUNT_INACTIVE #

605 - APP_NOT_AUTHORIZED #

2FA Errors (700-799) #

701 - TWO_FA_REQUIRED #

702 - TWO_FA_INVALID_TOKEN #

703 - TWO_FA_NOT_CONFIGURED #

704 - TWO_FA_EXPIRED #

Session Errors (800-899) #

801 - SESSION_EXPIRED #

802 - SESSION_INVALID #

803 - SESSION_NOT_FOUND #

Authorization Errors (900-999) #

901 - INSUFFICIENT_PERMISSIONS #

902 - ROLE_NOT_ALLOWED #

Input Validation Errors (1000-1099) #

1001 - MISSING_REQUIRED_FIELD #

1002 - INVALID_USERNAME_FORMAT #

1003 - INVALID_PASSWORD_LENGTH #

1004 - INVALID_TOKEN_FORMAT #

1005 - INVALID_AUTH_TOKEN #

1006 - API_TOKEN_EXPIRED #

1007 - TOKEN_SCOPE_INSUFFICIENT #

Rate Limiting (1100-1199) #

1101 - RATE_LIMIT_EXCEEDED #

Server Errors (1200-1299) #

1201 - INTERNAL_SERVER_ERROR #

1202 - DATABASE_ERROR #

1203 - CONFIGURATION_ERROR #

OAuth Errors (1300-1399) #

1301 - GITHUB_NOT_LINKED #

1302 - GITHUB_AUTH_FAILED #

1303 - OAUTH_STATE_MISMATCH #

API Usage #

Import Error Utilities #

Get Error Details #

Create Error Response #

Add Custom Data #

Log Errors #

Error Response Format #

Client-Side Error Handling #

JavaScript Example #

React Example #

Custom Error Messages #

Best Practices #

Security Considerations #

Examples #

Complete Login with Error Handling #

Support #

`601 - INVALID_CREDENTIALS` #

`602 - USER_NOT_FOUND` #

`603 - INCORRECT_PASSWORD` #

`604 - ACCOUNT_INACTIVE` #

`605 - APP_NOT_AUTHORIZED` #

`701 - TWO_FA_REQUIRED` #

`702 - TWO_FA_INVALID_TOKEN` #

`703 - TWO_FA_NOT_CONFIGURED` #

`704 - TWO_FA_EXPIRED` #

`801 - SESSION_EXPIRED` #

`802 - SESSION_INVALID` #

`803 - SESSION_NOT_FOUND` #

`901 - INSUFFICIENT_PERMISSIONS` #

`902 - ROLE_NOT_ALLOWED` #

`1001 - MISSING_REQUIRED_FIELD` #

`1002 - INVALID_USERNAME_FORMAT` #

`1003 - INVALID_PASSWORD_LENGTH` #

`1004 - INVALID_TOKEN_FORMAT` #

`1005 - INVALID_AUTH_TOKEN` #

`1006 - API_TOKEN_EXPIRED` #

`1007 - TOKEN_SCOPE_INSUFFICIENT` #

`1101 - RATE_LIMIT_EXCEEDED` #

`1201 - INTERNAL_SERVER_ERROR` #

`1202 - DATABASE_ERROR` #

`1203 - CONFIGURATION_ERROR` #

`1301 - GITHUB_NOT_LINKED` #

`1302 - GITHUB_AUTH_FAILED` #

`1303 - OAUTH_STATE_MISMATCH` #