Error Codes Reference

This document provides a comprehensive reference for all error codes used in the API. Each error includes a unique code, message, HTTP status, and category for easier debugging and error handling.

Error Structure

All errors follow a consistent structure:

{
  code: string;        // Unique error identifier (e.g., "AUTH_001")
  message: string;     // Human-readable error message
  httpStatus: number;  // HTTP status code
  category: string;    // Error category (e.g., "AUTH", "VALIDATION")
}

Error Categories

Usage Examples

Handling Errors in TypeScript

import { ErrorCodes } from './error-codes';
 
try {
  // API call
} catch (error) {
  if (error.code === ErrorCodes.AUTH_TOKEN_EXPIRED.code) {
    // Refresh token and retry
  } else if (error.code === ErrorCodes.TRANSACTION_INSUFFICIENT_BALANCE.code) {
    // Show insufficient balance error to user
  } else {
    // Handle other errors
  }
}

Filtering by Category

import { getErrorCodesByCategory } from './error-codes';
 
// Get all authentication errors
const authErrors = getErrorCodesByCategory('AUTH');
console.log(authErrors);

Getting All Categories

import { getErrorCategories } from './error-codes';
 
const categories = getErrorCategories();
// Returns: ['AUTH', 'VALIDATION', 'TRANSACTION', 'USER', 'SYSTEM', 'CHAIN', 'RESOURCE']

HTTP Status Code Summary

Best Practices

1. Always check the error code - Use the specific error code rather than just the HTTP status for precise error handling
2. Log error codes - Include error codes in your logs for easier debugging and monitoring
3. User-friendly messages - Map error codes to user-friendly messages in your frontend
4. Retry logic - Implement appropriate retry logic for transient errors (503, CHAIN_004)
5. Rate limiting - Handle RESOURCE_003 by implementing exponential backoff

Common Error Scenarios

Authentication Flow

1. AUTH_006 → AUTH_007 → AUTH_008 → Success
2. If any step fails, return the appropriate auth error

Transaction Processing

1. Validate input → VALIDATION_* errors
2. Check balance → TRANSACTION_002
3. Check limits → TRANSACTION_001 or TRANSACTION_006
4. Process → TRANSACTION_004 or CHAIN_* errors

User Operations

1. Validate address → USER_003
2. Check existence → USER_001 or USER_002
3. Check status → USER_004
4. Process operation