Error Codes
Complete reference of auth-svc error codes with HTTP status mappings and resolution guidance.
Error Response Format
Standard error envelopejson
{
"data": null,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid credentials",
"details": { "field": "email" }
},
"meta": {
"timestamp": "2026-02-24T12:00:00.000Z",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}| Code | HTTP | Name | Description | Resolution |
|---|---|---|---|---|
UNAUTHORIZED | 401 | Invalid Credentials | Email/password combination is incorrect | Verify email and password are correct |
ACCOUNT_SUSPENDED | 403 | Account Suspended | Account has been suspended by an admin | Contact platform administrator |
ACCOUNT_LOCKED | 423 | Account Locked | Too many failed login attempts | Wait for lockout period (15 min) or contact admin |
ACCOUNT_NOT_VERIFIED | 403 | Email Not Verified | Email address has not been verified | Check email for verification link or request new one |
MFA_REQUIRED | 200 | MFA Required | Account requires multi-factor authentication | Complete MFA challenge using /mfa/totp/verify |
| Code | HTTP | Name | Description | Resolution |
|---|---|---|---|---|
TOKEN_EXPIRED | 401 | Token Expired | JWT access token has expired | Refresh using /refresh endpoint with refresh token |
TOKEN_INVALID | 401 | Invalid Token | JWT signature is invalid or malformed | Re-authenticate to get new tokens |
TOKEN_REVOKED | 401 | Token Revoked | Token has been blacklisted (logout/compromised) | Re-authenticate to get new tokens |
REFRESH_TOKEN_EXPIRED | 401 | Refresh Token Expired | Refresh token has expired (7d default) | Full re-authentication required |
| Code | HTTP | Name | Description | Resolution |
|---|---|---|---|---|
SESSION_NOT_FOUND | 404 | Session Not Found | The specified session ID does not exist | Verify session ID or re-authenticate |
SESSION_EXPIRED | 401 | Session Expired | Session has timed out | Re-authenticate to create a new session |
MAX_SESSIONS_REACHED | 429 | Max Sessions | Maximum concurrent sessions reached | Revoke an existing session first |
| Code | HTTP | Name | Description | Resolution |
|---|---|---|---|---|
MFA_INVALID_CODE | 400 | Invalid MFA Code | The TOTP/OTP code is incorrect | Enter the correct code from authenticator app |
MFA_NOT_ENABLED | 400 | MFA Not Enabled | MFA has not been set up for this account | Enroll in MFA first via /mfa/totp/setup |
MFA_ALREADY_ENABLED | 409 | MFA Already Enabled | MFA is already enabled for this account | Disable MFA first if re-enrollment is needed |
| Code | HTTP | Name | Description | Resolution |
|---|---|---|---|---|
BAD_REQUEST | 400 | Bad Request | Request body failed validation | Check request body matches the DTO schema |
NOT_FOUND | 404 | Not Found | The requested resource does not exist | Verify the ID/path is correct |
CONFLICT | 409 | Conflict | Resource already exists (duplicate email, etc.) | Use a different identifier or update the existing resource |
RATE_LIMITED | 429 | Rate Limited | Too many requests in the time window | Wait and retry after the rate limit window resets |
FORBIDDEN | 403 | Forbidden | Insufficient permissions for this operation | Verify user has the required role (user/organizer/admin) |
Full Reference
For the complete 21-category error code reference with 100+ error codes, download the error-codes.md file from the Downloads page.