Error Codes

Error codes are standardized identifiers that help developers quickly understand and handle different types of failures in API requests. When an API call fails, the system returns a structured error response containing both an HTTP status code and a specific error code to provide precise information about what went wrong.

Understanding Error Responses

Every error response follows this format:

Error Response Structure

{
    "status": "error",
    "message": "Human-readable error description",
    "errorCode": "STANDARD_ERROR_CODE"
}

The error code serves multiple purposes:

Programmatic Handling - Allows your application to respond differently to different error types
Debugging - Helps developers quickly identify the root cause of issues
User Experience - Enables appropriate user-facing error messages
Monitoring - Facilitates error tracking and system health monitoring

Complete Error Code Reference

Client Errors (4xx)

These errors occur due to issues with the client request - invalid parameters, authentication problems, or malformed requests.

HTTP Status	Error Code	Error Message	Description	Common Causes
`400`	`BAD_REQUEST_ERROR`	BadRequestError	Missing or invalid request parameters or values	• Missing required fields • Invalid data format • Malformed JSON • Invalid parameter values
`401`	`UNAUTHORIZED`	UnAuthorized	Your session has expired. You must relogin to access the resource	• Expired authentication token • Missing API key • Invalid credentials • Session timeout
`403`	`FORBIDDEN`	Forbidden	You don't have permission to access this resource	• Insufficient user privileges • Resource access restrictions • Account limitations
`404`	`NOT_FOUND_ERROR`	NotFoundError	The requested resource could not be found	• Invalid endpoint URL • Resource has been deleted • Incorrect resource ID
`405`	`METHOD_NOT_ALLOWED`	Forbidden	The requested HTTP method is not allowed for this endpoint	• Using GET instead of POST • Using POST on read-only endpoint • Incorrect HTTP verb
`429`	`TOO_MANY_REQUESTS`	TooManyRequests	Rate limit exceeded - too many requests in a given time period	• Exceeding API rate limits • Burst request patterns • Multiple concurrent connections

Server Errors (5xx)

These errors indicate problems on the server side that are typically outside of the client's control.

HTTP Status	Error Code	Error Message	Description	Resolution
`500`	`INTERNAL_ERROR`	InternalError	An unexpected error occurred on the server	• Retry the request after a delay • Contact support if persistent • Check system status page
`502`	`OMS_ERROR`	OMSError	The Order Management System (OMS) is down or unreachable	• Retry after a few minutes • Check OMS system status • Use alternative endpoints if available

Error Handling Best Practices

1. Implement Proper Error Detection

Always check the response status before processing data:

JavaScript Error Detection

async function makeApiCall(endpoint, options) {
    try {
        const response = await fetch(endpoint, options);
        const data = await response.json();

        if (data.status === 'error') {
            throw new ApiError(data.errorCode, data.message, response.status);
        }

        return data.data;
    } catch (error) {
        handleApiError(error);
    }
}

2. Create Error-Specific Handling

Different error types require different responses:

Error-Specific Handling

function handleApiError(error) {
    switch (error.errorCode) {
        case 'UNAUTHORIZED':
            // Redirect to login page
            redirectToLogin();
            break;

        case 'TOO_MANY_REQUESTS':
            // Implement exponential backoff
            scheduleRetry(error.retryAfter);
            break;

        case 'NOT_FOUND_ERROR':
            // Show 404 page or fallback content
            showNotFoundMessage();
            break;

        case 'INTERNAL_ERROR':
        case 'OMS_ERROR':
            // Log error and show generic message
            logError(error);
            showServerErrorMessage();
            break;

        default:
            // Handle unexpected errors
            showGenericErrorMessage();
    }
}

3. Implement Retry Logic

For transient errors, implement smart retry mechanisms:

Retry Logic Example

async function retryableRequest(endpoint, options, maxRetries = 3) {
    const retryableErrors = ['INTERNAL_ERROR', 'OMS_ERROR', 'TOO_MANY_REQUESTS'];

    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            return await makeApiCall(endpoint, options);
        } catch (error) {
            if (!retryableErrors.includes(error.errorCode) || attempt === maxRetries) {
                throw error;
            }

            // Exponential backoff: 1s, 2s, 4s
            const delay = Math.pow(2, attempt - 1) * 1000;
            await sleep(delay);
        }
    }
}

Error Code Categories

Authentication & Authorization

UNAUTHORIZED - Session or credential issues
FORBIDDEN - Permission and access control issues

Request Validation

BAD_REQUEST_ERROR - Invalid request format or parameters
NOT_FOUND_ERROR - Resource doesn't exist
METHOD_NOT_ALLOWED - Incorrect HTTP method

Rate Limiting

TOO_MANY_REQUESTS - API usage limits exceeded

System Issues

INTERNAL_ERROR - General server problems
OMS_ERROR - Specific service unavailability

Troubleshooting Guide

Common Solutions by Error Type

`BAD_REQUEST_ERROR`

Validate request payload - Ensure all required fields are present
Check data formats - Verify dates, numbers, and other formatted fields
Review API documentation - Confirm parameter names and types
Test with minimal payload - Start with basic required fields only

`UNAUTHORIZED`

Check authentication token - Verify token is valid and not expired
Refresh session - Re-authenticate if session has timed out
Verify API key - Ensure API key is correctly configured
Check token format - Confirm proper Bearer token format

`TOO_MANY_REQUESTS`

Review rate limits - Check your current usage against limits
Implement request queuing - Space out API calls appropriately
Use bulk operations - Combine multiple operations where possible
Consider caching - Reduce redundant API calls

`INTERNAL_ERROR` / `OMS_ERROR`

Retry the request - Often temporary issues resolve quickly
Check system status - Verify if there are known service issues
Contact support - Report persistent errors with request details
Implement fallback logic - Use cached data or alternative workflows

Error Logging and Monitoring

For production applications, implement comprehensive error logging:

Error Logging Example

function logApiError(error, context) {
    const errorData = {
        timestamp: new Date().toISOString(),
        errorCode: error.errorCode,
        message: error.message,
        httpStatus: error.httpStatus,
        endpoint: context.endpoint,
        userId: context.userId,
        requestId: context.requestId,
        userAgent: navigator.userAgent
    };

    // Send to logging service
    logger.error('API Error', errorData);

    // Track metrics
    analytics.track('api_error', {
        error_code: error.errorCode,
        endpoint: context.endpoint
    });
}

Pro Tips

Always log the full error context, not just the error message
Set up alerts for error rate spikes or new error types
Monitor error patterns to identify systemic issues
Include request IDs in logs for easier debugging

HTTP Status Code Mapping

Understanding the relationship between HTTP status codes and our error codes:

HTTP Status	Category	Meaning	Action Required
`400`	Client Error	Bad request format	Fix request
`401`	Client Error	Authentication failed	Re-authenticate
`403`	Client Error	Access denied	Check permissions
`404`	Client Error	Resource not found	Verify resource exists
`405`	Client Error	Method not allowed	Use correct HTTP method
`429`	Client Error	Rate limited	Reduce request rate
`500`	Server Error	Internal server error	Retry or contact support
`502`	Server Error	Service unavailable	Wait and retry

This comprehensive error handling approach ensures robust, user-friendly applications that can gracefully handle various failure scenarios.