User Services
Error Codes Standardization Plan - Client Services

Error Codes Standardization Plan for Client-Related Services

Overview

This document outlines the plan to implement standardized error codes in the go-user-services repository for client-related services, following the 6-digit framework established in wallet-services.

Current State

Existing Error Code Usage

The service currently uses hardcoded error codes throughout client-related handlers:

  • 5004: Generic client/user errors (Email required, Phone required, User required, Email not valid, etc.)
  • 5999: Unknown/Internal errors (Unknown error, Something went wrong, etc.)
  • 5994: Bad request errors
  • 6092: User UUID validation errors, User already exists errors
  • 400: Validation errors

Files with Client-Related Error Codes

  • internal/app/user/caas_client.go - Main client user handlers (registration, updates, KYC)
  • internal/handlers/caas_user.go - Client user management handlers
  • internal/handlers/bank_account.go - Bank account operations for clients
  • internal/models/client/client.go - Client model operations
  • internal/routes/request/middlewares/middlewares.go - Middleware error handling

Standard Error Code Framework

Format

Following the wallet-services pattern: [Component][Sub-Component][Sequential]

  • Component: Identifies the service/system
  • Sub-Component: Identifies the functional area within the service
  • Sequential: Sequential error code within the sub-component

Component Number for User Services

Recommendation: Use component 5 (User Services)

  • Wallet services use 4 (Transactions System)
  • User services should use 5 to maintain clear separation
  • Alternative: Use 2 if there's an existing convention, but 5 is recommended for clarity

Sub-Components for Client-Related Services

Sub-ComponentAreaDescription
01Client User ManagementUser registration, updates, retrieval, deletion
02KYC OperationsKYC submission, validation, status updates, deduplication
03Client ConfigurationClient settings, webhooks, requirements
04Authentication & AuthorizationToken validation, client authentication, permissions
05Bank Account OperationsBank account addition, validation, verification
06-09ReservedFor future client-related features
10-13ReservedFor other user-services features (non-client)

Proposed Error Code Mappings

General Errors (50xxxx)

500001 - Missing or Invalid Parameters

  • HTTP Status: 400 Bad Request
  • Description: Missing or invalid parameters in the request
  • Current Codes: 400, 5004 (validation cases)
  • When to Use: Request parameters are missing, malformed, or contain invalid data types

509999 - General Internal Server Error

  • HTTP Status: 500 Internal Server Error
  • Description: Generic system error used for masked 5xx responses
  • Current Codes: 5999 (generic errors)
  • When to Use: Internal server errors where actual error details should not be exposed

Client User Management Errors (Sub-component 01)

501001 - User Required

  • HTTP Status: 400 Bad Request
  • Description: User ID or user identifier is required but missing
  • Current Code: 5004 ("User is required.")
  • When to Use: When userID is 0 or user identifier is missing in request

501002 - User Already Exists

  • HTTP Status: 409 Conflict
  • Description: User already exists with the provided identifiers
  • Current Code: 6092 ("User Already Exist, Check client_user_id or user_uuid or Email or Phone")
  • When to Use: When attempting to register a user that already exists (duplicate user_uuid, client_user_id, email, or phone)

501003 - Invalid User UUID

  • HTTP Status: 400 Bad Request
  • Description: Invalid user UUID format
  • Current Code: 6092 ("INvalid User UUID")
  • When to Use: When user UUID format validation fails

501004 - Email Required

  • HTTP Status: 400 Bad Request
  • Description: Email is required but missing
  • Current Code: 5004 ("Email is required")
  • When to Use: When email is required by client configuration but not provided

501005 - Phone Required

  • HTTP Status: 400 Bad Request
  • Description: Phone is required but missing
  • Current Code: 5004 ("Phone is required")
  • When to Use: When phone is required by client configuration but not provided

501006 - Invalid Email Format

  • HTTP Status: 400 Bad Request
  • Description: Email format is invalid
  • Current Code: 5004 ("Email is not valid")
  • When to Use: When email validation fails (format, length, etc.)

501007 - Email or Phone Update Not Allowed

  • HTTP Status: 400 Bad Request
  • Description: Email or phone update is not allowed for this user
  • Current Code: 5004 ("Email or Phone update is not allowed")
  • When to Use: When attempting to update email or phone which is restricted

501008 - At Least One Field Required

  • HTTP Status: 400 Bad Request
  • Description: At least one field (email, phone, or NRI status) is required for update
  • Current Code: 5004 ("Email or Phone or Nri status is required")
  • When to Use: When update request has no valid fields to update

501009 - User Registration Failed

  • HTTP Status: 500 Internal Server Error
  • Description: Failed to register user in auth service
  • Current Code: 5004 ("Error registering user"), 6092 ("unable to crete user")
  • When to Use: When user registration in auth service fails

501010 - User Not Found

  • HTTP Status: 404 Not Found
  • Description: User not found for the specified client
  • Current Code: Various
  • When to Use: When user does not exist or does not belong to the client

KYC Operations Errors (Sub-component 02)

502001 - KYC Deduplication Failed

  • HTTP Status: 400 Bad Request
  • Description: KYC documents already exist for another user
  • Current Code: 5004 (various dedupe messages)
  • When to Use: When POA/POI/Email/Phone already exists for another user

502002 - Invalid Country Code

  • HTTP Status: 400 Bad Request
  • Description: Invalid or unsupported country code
  • Current Code: Various ("invalid country code passed")
  • When to Use: When country ISO3 code is invalid or not supported

502003 - KYC Documents Required

  • HTTP Status: 400 Bad Request
  • Description: Required KYC documents (POA/POI) are missing
  • Current Code: 5004 (validation errors)
  • When to Use: When POA or POI is missing from KYC submission

502004 - KYC Validation Failed

  • HTTP Status: 400 Bad Request
  • Description: KYC validation failed
  • Current Code: Various
  • When to Use: When KYC validation logic fails (nationality restrictions, etc.)

502005 - KYC Service Error

  • HTTP Status: 500 Internal Server Error
  • Description: Error communicating with KYC service
  • Current Code: 5999 (various KYC service errors)
  • When to Use: When external KYC service calls fail

502006 - KYC Status Update Failed

  • HTTP Status: 500 Internal Server Error
  • Description: Failed to update KYC status
  • Current Code: Various
  • When to Use: When KYC status update operation fails

Client Configuration Errors (Sub-component 03)

503001 - Client Not Found

  • HTTP Status: 404 Not Found
  • Description: Client not found
  • Current Code: Various
  • When to Use: When client ID does not exist

503002 - Client Configuration Error

  • HTTP Status: 500 Internal Server Error
  • Description: Error retrieving client configuration
  • Current Code: 5004 ("Error registering user" - when getting requirements fails)
  • When to Use: When client configuration retrieval fails

Authentication & Authorization Errors (Sub-component 04)

504001 - Missing or Invalid Auth Token

  • HTTP Status: 401 Unauthorized
  • Description: Missing or invalid authentication token
  • Current Code: Various (middleware errors)
  • When to Use: When auth token is missing, invalid, or expired

504002 - Client Authentication Failed

  • HTTP Status: 401 Unauthorized
  • Description: Client authentication failed
  • Current Code: Various
  • When to Use: When client ID validation fails or client is not authorized

504003 - KYC Token Retrieval Failed

  • HTTP Status: 500 Internal Server Error
  • Description: Failed to retrieve KYC token for client
  • Current Code: 5999 ("Unknown error")
  • When to Use: When GetClientKycToken fails

Bank Account Operations Errors (Sub-component 05)

505001 - Bank Account Validation Failed

  • HTTP Status: 400 Bad Request
  • Description: Bank account validation failed
  • Current Code: Various
  • When to Use: When bank account details (IFSC, account number, etc.) validation fails

505002 - Bank Account Already Exists

  • HTTP Status: 409 Conflict
  • Description: Bank account already exists
  • Current Code: Various
  • When to Use: When attempting to add a duplicate bank account

Implementation Plan

Phase 1: Error Code Constants Definition

  1. Create error code constants file

    • Location: internal/constants/error_codes.go
    • Define all error codes as constants
    • Group by sub-component for maintainability

  2. Create error code helper functions

    • Location: internal/utils/error_codes.go (or extend existing utils)
    • Functions to create standardized error responses
    • Helper to map HTTP status codes

Phase 2: Update Client User Handlers

  1. Update internal/app/user/caas_client.go

    • Replace hardcoded error codes with constants
    • Map existing error scenarios to new codes:
      • GetClientKycToken → 504003
      • AddClientUserHandler → 501001-501010
      • EditClientUserHandler → 501001, 501006-501008
      • AddCaasClientKycHandler → 502001-502006

  2. Update internal/handlers/caas_user.go

    • Replace hardcoded error codes
    • Map to appropriate sub-component codes

Phase 3: Update Supporting Files

  1. Update internal/models/client/client.go

    • Replace error codes in model operations
    • Ensure consistent error handling

  2. Update internal/routes/request/middlewares/middlewares.go

    • Update middleware error codes
    • Use 504001 for auth failures

  3. Update internal/handlers/bank_account.go

    • Map bank account errors to 505xxx codes

Phase 4: Validation Error Handling

  1. Update internal/utils/utils.go

    • Update HandleValidationErrorsWithLanguage to use 500001
    • Ensure validation errors use standardized codes

  2. Review and update validators

    • Ensure all validation errors map to appropriate codes

Phase 5: Testing & Documentation

  1. Update tests

    • Update test cases to expect new error codes
    • Add tests for error code mapping

  2. Update API documentation

    • Document all error codes in API docs
    • Update error response examples

  3. Create migration guide

    • Document old code → new code mappings
    • For clients consuming the API

Migration Strategy

Backward Compatibility Considerations

  1. Gradual Migration

    • Consider maintaining old codes temporarily with deprecation warnings
    • Or migrate all at once with clear communication

  2. Client Communication

    • Notify API consumers of error code changes
    • Provide mapping document for transition period

  3. Monitoring

    • Monitor error code usage after migration
    • Track any issues with new codes

Example Implementation

Error Code Constants

package constants
 
// Component 5: User Services
const (
    // General Errors (50xxxx)
    ErrCodeMissingInvalidParams = 500001
    ErrCodeInternalServerError   = 509999
 
    // Client User Management (501xxx)
    ErrCodeUserRequired              = 501001
    ErrCodeUserAlreadyExists         = 501002
    ErrCodeInvalidUserUUID           = 501003
    ErrCodeEmailRequired             = 501004
    ErrCodePhoneRequired             = 501005
    ErrCodeInvalidEmailFormat        = 501006
    ErrCodeEmailPhoneUpdateNotAllowed = 501007
    ErrCodeAtLeastOneFieldRequired   = 501008
    ErrCodeUserRegistrationFailed    = 501009
    ErrCodeUserNotFound              = 501010
 
    // KYC Operations (502xxx)
    ErrCodeKYCDeduplicationFailed = 502001
    ErrCodeInvalidCountryCode      = 502002
    ErrCodeKYCDocumentsRequired    = 502003
    ErrCodeKYCValidationFailed     = 502004
    ErrCodeKYCServiceError          = 502005
    ErrCodeKYCStatusUpdateFailed    = 502006
 
    // Client Configuration (503xxx)
    ErrCodeClientNotFound         = 503001
    ErrCodeClientConfigurationError = 503002
 
    // Authentication & Authorization (504xxx)
    ErrCodeMissingInvalidAuthToken = 504001
    ErrCodeClientAuthenticationFailed = 504002
    ErrCodeKYCTokenRetrievalFailed = 504003
 
    // Bank Account Operations (505xxx)
    ErrCodeBankAccountValidationFailed = 505001
    ErrCodeBankAccountAlreadyExists     = 505002
)

Helper Function Example

package utils
 
import (
    "github.com/mudrex/go-user-services/internal/constants"
    "github.com/mudrex/baseplate.go/v2/router/gin/response"
)
 
func NewErrorResponse(code int, message string) response.Error {
    return response.Error{
        Code: code,
        Text: message,
    }
}
 
func UserRequiredError() response.Error {
    return NewErrorResponse(
        constants.ErrCodeUserRequired,
        "User is required.",
    )
}

Usage Example

// Before
c.JSON(http.StatusBadRequest, response.ErrorResponseObj(response.Error{
    Code: 5004,
    Text: "User is required.",
}))
 
// After
c.JSON(http.StatusBadRequest, response.ErrorResponseObj(
    utils.UserRequiredError(),
))

Next Steps

  1. Review and approve this plan with the team
  2. Confirm component number (5 recommended, or alternative if convention exists)
  3. Create error code constants file with all defined codes
  4. Implement Phase 1 (constants and helpers)
  5. Begin Phase 2 (update handlers incrementally)
  6. Test thoroughly before full deployment
  7. Communicate changes to API consumers

Notes

  • This plan focuses on client-related services only
  • Other user-services features (non-client) should use different sub-components (10-13)
  • Error messages should remain user-friendly and descriptive
  • Consider adding error code to logging for better traceability
  • Future error codes should follow the same pattern and be documented
User Services API StatusAPI Endpoints Migration - Saber Money