Skip to main content
This document provides a comprehensive guide to the error handling system used in the HIFI API. Understanding these error codes will help you effectively handle exceptions and communicate issues to your users.

Error Code Structure

Error codes follow a consistent format that provides information about the source and type of error: SSCEESS Where:
  • SS: Service identifier (2 digits)
  • C: Error category (2 digits)
  • EE: Error sequence (2 digits)
Example: Error code 100001 indicates a generic validation error (Service ID: 10, Category: 00, Sequence: 01).
Service IDDescription
10Generic Services
20Authentication
30User Management
40Transaction Processing
50Account Management
60Wallet Services
70System Infrastructure
Category IDDescription
00Validation Error
01Authentication Error
02Authorization Error
03Not Found Error
04Service Unavailable
05Inactive Resource

Error Response Format

All error responses follow a consistent JSON structure:
{
  "code": 100001,
  "error": "FIELD_VALIDATION_ERROR",
  "errorDetails": "Fields provided are either missing or invalid"
}

Error Code Reference

CodeErrorDescription
100001FIELD_VALIDATION_ERRORFields provided are either missing or invalid
100002METHOD_NOT_ALLOWEDMethod not allowed
100003INVALID_VERSIONInvalid version
100004DEPRECATED_RESOURCEThis resource has been deprecated
100005RESOURCE_CONFLICTResource conflict, please try different request id
CodeErrorDescription
200001INVALID_API_KEYInvalid API key
200201PRODUCTION_NOT_ENABLEDProduction is not enabled for this profile
200202USER_ROLE_NOT_ALLOWEDUser role not allowed to perform this action
200203UNAUTHORIZEDUnauthorized
200204PROFILE_FROZENProfile is not authorized to access this resource
200301BILLING_CONFIG_NOT_FOUNDBilling configuration not found
200301KEY_DOES_NOT_EXISTKey does not exist
CodeErrorDescription
300001USER_ALREADY_EXISTSUser already exists
300201USER_ACTION_NOT_ALLOWEDUser is not allowed to perform this action
300201USER_COMPLIANCE_VERIFICATION_FAILEDUser compliance information is not approved
300202USER_COMPLIANCE_DATA_INVALIDUser compliance data is invalid
300202USER_FROZENUser is not authorized to access this resource
300301USER_NOT_FOUNDUser not found
CodeErrorDescription
400001INVALID_TRANSACTION_ROUTEInvalid transaction route (combination of currency, crypto, and rail)
400002INVALID_ACCOUNT_FOR_TRANSACTIONInvalid bank account for the transaction
400003TRANSACTION_REQUEST_ALREADY_EXISTSTransaction request already exists
400005QUOTE_NOT_READYQuote is not ready yet
400006INVALID_QUOTEExpired or invalid quote
400301TRANSACTION_NOT_FOUNDTransaction not found
400302QUOTE_NOT_FOUNDQuote not found
400401INSUFFICIENT_BALANCEInsufficient balance for transaction
400402INSUFFICIENT_CREDIT_BALANCEInsufficient credit balance for transaction fee
400403TRANSACTION_INITIATION_FAILEDTransaction initiation failed
CodeErrorDescription
500001INVALID_ACCOUNT_DATAInvalid bank account data provided
500301ACCOUNT_NOT_FOUNDBank account ID not found
500501INACTIVE_ACCOUNTBank account is not active
CodeErrorDescription
600001INVALID_WALLET_CONFIGInvalid wallet configuration provided
600001WALLET_ALREADY_EXISTSWallet already exists for this configuration
600301WALLET_NOT_FOUNDWallet not found for the user
600501INACTIVE_WALLETWallet is not active
CodeErrorDescription
700401INTERNAL_SERVER_ERRORInternal server error

Usage Examples

JavaScript

try {
  // API call
  const response = await fetch("/api/transfers", {
    method: "POST",
    headers: {
      Authorization: "Bearer " + apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(transferData),
  });

  if (!response.ok) {
    const error = await response.json();
    throw error;
  }
} catch (error) {
  if (error.code === 300301) {
    // Handle USER_NOT_FOUND error
    console.log("User was not found in the system");
  } else if (error.code === 400401) {
    // Handle INSUFFICIENT_BALANCE error
    console.log("Transaction failed due to insufficient balance");
  } else if (error.code === 200001) {
    // Handle INVALID_API_KEY error
    console.log("Please check your API key");
  }
}

HTTP Response Example

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": 400001,
  "error": "INVALID_TRANSACTION_ROUTE",
  "errorDetails": "Invalid transaction route with the provided transaction details"
}

Best Practices

Error Handling

  1. Always check error codes before displaying generic error messages
  2. Implement retry logic for transient errors (5xx status codes)
  3. Log errors for debugging and monitoring purposes
  4. Provide user-friendly messages based on error codes

Common Error Scenarios

  • Authentication Issues: Check API key validity and permissions
  • User Not Found: Verify user exists and is properly created
  • Insufficient Balance: Check account balances before transactions
  • Invalid Routes: Ensure currency/crypto/rail combinations are supported

Error Code Patterns

  • 1xxxxx: Generic validation and system errors
  • 2xxxxx: Authentication and authorization issues
  • 3xxxxx: User-related problems
  • 4xxxxx: Transaction processing errors
  • 5xxxxx: Account management issues
  • 6xxxxx: Wallet service problems
  • 7xxxxx: System infrastructure errors
I