Error Code Reference

Complete list of error codes used in EZ-Console.

Error Code Format

Format: E + HTTP status code + sequence number

Example: E4001 = Error 400 (Bad Request), sequence 01

Client Errors (4xx)

Bad Request (400)

Code	Description	Solution
E4001	Invalid request parameters	Check request format and required fields
E4002	Validation failed	Fix validation errors in request body
E4003	Invalid JSON format	Ensure request body is valid JSON
E4004	Invalid UUID format	Use valid UUID format
E4005	Invalid email format	Use valid email address
E4006	Invalid date format	Use ISO 8601 format

Unauthorized (401)

Code	Description	Solution
E4012	Invalid or missing auth token	Login again to get new token
E4013	Token expired	Refresh token or login again
E4014	Invalid credentials	Check username and password
E4015	Account locked	Contact administrator
E4016	MFA required	Provide MFA code

Forbidden (403)

Code	Description	Solution
E4031	Permission denied	Request permission from administrator
E4032	Insufficient permissions	Check your role permissions
E4033	Account disabled	Contact administrator
E4034	Password expired	Change your password

Not Found (404)

Code	Description	Solution
E4041	Resource not found	Check resource ID
E4042	User not found	Verify user exists
E4043	Endpoint not found	Check API endpoint

Conflict (409)

Code	Description	Solution
E4091	Resource already exists	Use different name or identifier
E4092	Username already exists	Choose different username
E4093	Email already exists	Use different email

Unprocessable Entity (422)

Code	Description	Solution
E4221	Business rule violation	Review business rules
E4222	Insufficient stock	Check available quantity
E4223	Invalid state transition	Check current state

Too Many Requests (429)

Code	Description	Solution
E4291	Rate limit exceeded	Wait and retry later

Server Errors (5xx)

Internal Server Error (500)

Code	Description	Solution
E5001	Internal server error	Contact support with error details
E5002	Database error	Check database connection and logs
E5003	External service error	Check external service status
E5004	File operation error	Check file permissions
E5005	Configuration error	Verify configuration

Service Unavailable (503)

Code	Description	Solution
E5031	Service temporarily unavailable	Try again later
E5032	Database unavailable	Check database status
E5033	Maintenance mode	Wait for maintenance to complete

Error Response Format

All errors follow this format:

{
  "code": "E4001",
  "err": "Human-readable error message"
}

Handling Errors

Frontend

try {
  const data = await apiGet('/users');
} catch (error) {
  const errorCode = error.response?.data?.code;
  const errorMessage = error.response?.data?.err;
  
  switch (errorCode) {
    case 'E4012':
      // Redirect to login
      window.location.href = '/login';
      break;
    case 'E4031':
      message.error('Permission denied');
      break;
    default:
      message.error(errorMessage || 'An error occurred');
  }
}

Backend

product, err := c.svc.Product().GetByID(ctx.Request.Context(), id)
if err != nil {
    if errors.Is(err, service.ErrNotFound) {
        util.RespondWithError(ctx, util.NewErrorMessage("E4041", "Product not found"))
        return
    }
    util.RespondWithError(ctx, util.NewErrorMessage("E5001", "Failed to get product", err))
    return
}

Logging

All errors are automatically logged with context:

{
  "level": "error",
  "msg": "Failed to get product",
  "code": "E5001",
  "err": "database connection failed",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user-uuid",
  "timestamp": "2024-01-01T12:00:00Z"
}

Best Practices

DO ✅

1. Use appropriate error codes
2. Provide helpful error messages
3. Log detailed errors server-side
4. Return sanitized errors to clients
5. Handle specific error cases

DON'T ❌

1. Don't expose internal errors
2. Don't return stack traces
3. Don't ignore error handling
4. Don't use generic errors everywhere
5. Don't expose sensitive information

Next Steps

• Learn about error handling
• Review API best practices
• Check troubleshooting guide